<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>  <title>IC Programmers Manual</title><!-- 01-05-2006 version --></head><body><br><center><font size="+4"><b>IC Programmers Manual for the Xport BotballController</b></font><br></center><!----><a name="PM_Index"></a><center><font size="+3"><b>Programmers Manual Index</b></font><br></center><ol>  <li><a href="#Introduction">Introduction</a><br>  </li>  <li><a href="#Using_IC">Using IC</a><br>  </li>  <li><a href="#IC_Interface">IC Interface</a><br>  </li>  <li><a href="#The_main_Function">The main() Function</a><br>  </li>  <li><a href="#IC_versus_Standard_C">IC versus Standard C</a><br>    <ul type="disc">      <li><a href="#A_Quick_C_Tutorial">A Quick C Tutorial</a><br>        <ul>          <li><a href="#return_type">return type</a><br>          </li>          <li><a href="#return_statement">return statement</a><br>          </li>        </ul>      </li>    </ul>  </li>  <li><a href="#Data_Objects">Data Objects</a><br>    <ul type="disc">      <li><a href="#Variables">Variables</a><br>        <ul>          <li><a href="#Declaration">Declaration</a><br>          </li>          <li><a href="#Local_and_Global_Scopes">Local and GlobalScopes</a><br>          </li>          <li><a href="#Variable_Initialization">VariableInitialization</a><br>          </li>          <li><a href="#Persistent_Global_Variables">PersistentGlobal Variables</a><br>          </li>        </ul>      </li>      <li><a href="#Constants">Constants</a><br>        <ul>          <li><a href="#Integer_Constants">Integer Constants</a><br>          </li>          <li><a href="#Long_Integer_Constants">Long IntegerConstants</a><br>          </li>          <li><a href="#Floating_Point_Constants">Floating PointConstants</a><br>          </li>          <li><a href="#Characters_and_String_Constants">Charactersand String Constants</a><br>          </li>          <li><a href="#Integer_Constants">Integer Constants</a><br>          </li>          <li><a href="#NULL">NULL</a><br>          </li>        </ul>      </li>      <li><a href="#Data_Types">Data Types</a><br>        <ul>          <li><a href="#16-bit_Integers">16-bit Integers</a><br>          </li>          <li><a href="#32-bit_Integers">32-bit Integers</a><br>          </li>          <li><a href="#32-bit_Floating_Point_Numbers">32-bitFloating Point Numbers</a><br>          </li>          <li><a href="#8-bit_Characters">8-bit Characters</a><br>          </li>          <li><a href="#Pointers">Pointers</a><br>          </li>          <li><a href="#Arrays">Arrays</a><br>          </li>          <li><a href="#Structures">Structures</a><br>          </li>        </ul>      </li>      <li><a href="#PointersM">Pointers</a><br>        <ul>          <li><a href="#Pointer_Safety">Pointer Safety</a><br>          </li>          <li><a href="#Pointer_Declaration_and_Use">PointerDeclaration and Use</a><br>          </li>          <li><a href="#Passing_Pointers_as_Arguments">PassingPointers as Arguments</a><br>          </li>          <li><a href="#Returning_Pointers_from_Functions">ReturningPointers from Functions</a><br>          </li>        </ul>      </li>      <li><a href="#Arrays">Arrays</a><br>        <ul>          <li><a href="#Declaring_and_Initializing_Arrays">Declaringand Initializing Arrays</a><br>          </li>          <li><a href="#Passing_Arrays_as_Arguments">PassingArrays as Arguments</a><br>          </li>          <li><a href="#Multi-dimensional_Arrays">Multi-dimensionalArrays</a><br>          </li>          <li><a href="#Determining_the_size_of_Arrays_at_Runtime">Determiningthe size of Arrays at Runtime</a><br>          </li>          <li><a href="#Uploading_Arrays">Uploading Arrays</a><br>          </li>        </ul>      </li>      <li><a href="#Structures2">Structures</a><br>      </li>      <li><a href="#Complex_Initialization_examples">ComplexInitialization examples</a><br>      </li>    </ul>  </li>  <li><a href="#Statements_and_Expressions">Statements andExpressions</a><br>    <ul type="disc">      <li><a href="#Operators">Operators</a><br>        <ul>          <li><a href="#Integer_Operations">Integer Operations</a><br>          </li>          <li><a href="#Long_Integers">Long Integers</a><br>          </li>          <li><a href="#Floating_Point_Numbers">Floating PointNumbers</a><br>          </li>          <li><a href="#Characters">Characters</a><br>          </li>        </ul>      </li>    </ul>  </li>  <li><a href="#Assignment_Operators_and_Expressions">AssignmentOperators and Expressions</a><br>  </li>  <li><a href="#Increment_and_Decrement_Operators">Increment andDecrement Operators</a><br>  </li>  <li><a href="#Data_Access_Operators">Data Access Operators</a><br>  </li>  <li><a href="#Precedence_and_Order_of_Evaluation">Precedenceand Order of Evaluation</a><br>  </li>  <li><a href="#Control_Flow">Control Flow</a><br>  </li>  <li><a href="#Statements_and_Blocks">Statements and Blocks</a><br>    <ul type="disc">      <li><a href="#If-Else">If-Else</a><br>      </li>      <li><a href="#While">While</a><br>      </li>      <li><a href="#Do-While">Do-While</a><br>      </li>      <li><a href="#For">For</a><br>      </li>      <li><a href="#Switch">Switch</a><br>      </li>      <li><a href="#Break">Break</a><br>      </li>    </ul>  </li>  <li><a href="#LCD_Screen_Printing">LCD Screen Printing</a><br>    <ul type="disc">      <li><a href="#Printing_Examples">Printing Examples</a><br>        <ul>          <li><a href="#Printing_a_message">Printing a message</a><br>          </li>          <li><a href="#Printing_a_number">Printing a number</a><br>          </li>          <li><a href="#Printing_a_number_in_binary">Printing anumber in binary</a><br>          </li>          <li><a href="#Printing_a_floating_point_number">Printinga floating point number</a><br>          </li>          <li><a href="#Printing_two_numbers_in_hexadecimal_format">Printingtwo numbers in hexadecimal format</a><br>          </li>        </ul>      </li>      <li><a href="#Formatting_Command_Summary">Formatting CommandSummary</a><br>      </li>    </ul>  </li>  <li><a href="#Preprocessor">Preprocessor</a><br>    <ul type="disc">      <li><a href="#Preprocessor_Macros">Preprocessor Macros</a><br>      </li>      <li><a href="#Conditional_compilation">Conditional compilation</a><br>      </li>      <li><a href="#Comparison_with_regular_C_preprocessors">Comparisonwith regular C preprocessors</a><br>      </li>    </ul>  </li>  <li><a href="#The_IC_Library_File">The IC Library File</a><br>    <ul type="disc">      <li><a href="#Commonly_Used_IC_Library_Functions">CommonlyUsed IC Library Functions</a><br>        <ul>          <li><a href="#digitalx"><font color="darkblue">digital</font></a><br>          </li>          <li><a href="#analogx"><font color="darkblue">analog</font></a><br>          </li>          <li><a href="#sleepx"><font color="darkblue">sleep</font></a><br>          </li>          <li><a href="#beepx"><font color="darkblue">beep</font></a><br>          </li>          <li><a href="#tonex"><font color="darkblue">tone</font></a><br>          </li>          <li><a href="#printfx"><font color="darkblue">printf</font></a><br>          </li>          <li><a href="#motorx"><font color="darkblue">motor</font></a><br>          </li>          <li><a href="#fdx"><font color="darkblue">fd</font></a><br>          </li>          <li><a href="#bkx"><font color="darkblue">bk</font></a><br>          </li>          <li><a href="#offx"><font color="darkblue">off</font></a><br>          </li>          <li><a href="#aox"><font color="darkblue">ao</font></a><br>          </li>        </ul>      </li>      <li><a href="#Processes">Processes</a><br>        <ul>          <li><a href="#start_processx"><font color="darkblue">start_process</font></a><br>          </li>          <li><a href="#deferx"><font color="darkblue">defer</font></a><br>          </li>          <li><a href="#kill_processx"><font color="darkblue">kill_process</font></a><br>          </li>        </ul>      </li>      <li><a href="#Encoders">Encoders</a><br>        <ul>          <li><a href="#xenable_encoder"><font color="darkblue">enable_encoder</font></a><br>          </li>          <li><a href="#xdisable_encoder"><font color="darkblue">disable_encoder</font></a><br>          </li>          <li><a href="#xreset_encoder"><font color="darkblue">reset_encoder</font></a><br>          </li>          <li><a href="#xread_encoder"><font color="darkblue">read_encoder</font></a><br>          </li>        </ul>      </li>    </ul>  </li>  <li><a href="#sensors">Sensors</a></li>  <li><a href="#Functions">Alphabetic List of Functions</a></li>  <li><A href="#Vision">IC Vision API for the XBC</A></LI>  <li><a href="#Simulator">Simulator Instructions</a></li></ol><a name="Introduction"></a><font size="+3"><b>Introduction</b></font><p>Interactive C (IC for short) is a C language consisting of acompiler (with interactive command-linecompilation and debugging) and a run-time machine language module. ICimplements a subset of C includingcontrol structures (<a href="#For"><font color="blue">for</font></a>, <a href="#While"><font color="blue">while</font></a>,<a href="#If-Else"><font color="blue">if</font></a>, <a href="#If-Else"><font color="blue">else</font></a>), local and global variables, arrays,pointers, structures,16-bit and 32-bit integers, and 32-bit floating point numbers.</p><p>IC works by compiling into pseudo-code for a custom stack machine,rather than compiling directly intonative code for a particular processor. This pseudo-code (or <i>p-code</i>)is then interpreted by the run-timemachine language program. This unusual approach to compiler designallows IC to offer the following designtradeoffs:</p><ul>  <li><b>Interpreted execution</b> that allows run-time error checking.For example, IC doesarray bounds checking at run-time to protect against some programmingerrors.  </li>  <li><b>Ease of design</b>. Writing a compiler for a stack machine issignificantly easier thanwriting one for a typical processor. Since IC's p-code ismachine-independent,porting IC to another processor entails rewriting the p-codeinterpreter, rather thanchanging the compiler.  </li>  <li><b>Small object code</b>. Stack machine code tends to be smallerthan a native coderepresentation.  </li>  <li><b>Multi-tasking</b>. Because the pseudo-code is fullystack-based, a process's state isdefined solely by its stack and its program counter. It is thus easy totask-switchsimply by loading a new stack pointer and program counter. Thistask-switchingis handled by the run-time module, not by the compiler.  </li></ul>Since IC's ultimate performance is limited by the fact that its outputp-code is interpreted,these advantages are taken at the expense of raw execution speed.<table>  <tbody>    <tr>      <td><font face="Times"></font>      <dl>        <dd><font face="Times"><i>IC 5 was written by KyleMachulis/KISS Institute for Practical Robotics. Portions of the codeand the libraries arebased on the public distribution of IC 4.x by Randy Sargent withassistance from Mark Sherman, and IC 2.8,written by Randy Sargent, Anne Wright and Fred Martin.          </i></font></dd>      </dl>      </td>    </tr>  </tbody></table><br><!----><a name="Using_IC"></a><font size="+3"><b>Using IC</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>When IC is running and has a connection to a compatible processorboard such as theHandy Board or RCX, C expressions, function calls, and IC commands maybe typed inthe command entry portion of the interaction window.</p><p>For example, to evaluate the arithmetic expression 1 + 2, type inthe following:<table>  <tbody>    <tr>      <td>      <pre>   1 + 2;</pre>      </td>    </tr>  </tbody></table>When this expression is entered from the interaction window, it iscompiled by theconsole computer and then downloaded to the attached system forevaluation. Theconnected board then evaluates the compiled form and returns theresult, which is printedon the display section of console interaction window.</p><p>To evaluate a series of expressions, create a C block by beginningwith an open curlybrace { and ending with a close curly brace }. The following examplecreates a localvariable <font face="Courier">i</font> and prints 10 (the sum of <font face="Courier">i + 7</font>) to the board's LCD screen:<table>  <tbody>    <tr>      <td>      <pre>   {<font color="blue">int</font> i=3; <font color="purple">printf</font>(<font color="red">"%d"</font>, i+7);}</pre>      </td>    </tr>  </tbody></table><br><!----><a name="IC_Interface"></a><font size="+2"><b>IC Interface</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Both new (unsaved) and saved files can be opened for editing in IC.A row of tabs liststhe files that have been opened. Clicking a file's tab activates it forediting. The first tabfor the interface is always the interaction window.</p><p>The <font face="Ariel"><b><u>F</u>ile</b></font> button hasstandard entries for<font face="Ariel"><b><u>N</u>ew</b></font>, <font face="Ariel"><b><u>O</u>pen</b></font>,<font face="Ariel"><b><u>C</u>lose</b></font>,<font face="Ariel"><b><u>S</u>ave</b></font>, <font face="Ariel"><b>Save<u>A</u>s</b></font>, <font face="Ariel"><b><u>P</u>rint</b></font>,and<font face="Ariel"><b>E<u>x</u>it</b></font>. Under <font face="Ariel"><b><u>F</u>ile- Save <u>A</u>s</b></font>,if no file name extension is supplied, IC automatically saveswith the "<b><font face="Courier">.ic</font></b>" extension.</p><p>To download the active file, simply click the download button. Theactive file will alsobe saved, unless it is new, in which case the user is prompted for a"save as" file name.Remark: a <a href="#Preprocessor">preprocessor</a> command <font color="blue" face="Courier">#use</font> has been added to IC tospecify any other savedfiles (personal libraries) that need to be downloaded along with theactive file [Note:<font color="blue" face="Courier">#use</font> is quite different fromthe<font face="Courier">#include</font> prepreocessor command of standardCenvironments. <font face="Courier">#include</font> is not implementedfor reasons given later in the sectiondescribing the IC-preprocessor.]</p><p>If a downloaded program does not do what is intended, it may corruptthe p-codeinterpreter, particularly if pointers are being employed. The interfaceprovides an optionunder the <font face="Ariel"><b><u>S</u>ettings</b></font> button fordownloading the firmware to reinitialize the board.</p><p>When there is a connection to a board and the downloaded programsinclude "main", then"main" can be executed using the <font face="Ariel"><b>Run Main</b></font>button.The <font face="Ariel"><b>Stop</b></font> button will halt executionof the attached system.</p><p>Under the <font face="Ariel"><b><u>T</u>ools</b></font> button,among other options, are ones for listing downloaded files,global variables, and functions (including library functions).</p><p>The interface provides additional capabilities for programentry/edit, minor adjustment tothe display, and for setting up the serial interface to a board. Inparticular, the <b>Check</b> tool will performa syntax check of the C program currently in the window. If there is anerror, the approximate linenumber where the error is located is reported (the error is on the lineor a nearby prior line). The editbutton provides a <font face="Ariel"><b><u>G</u>o to line</b></font>option.</p><p>C programs are automatically formatted and indented. Keywords,library functions,comments, and text strings are high-lighted with color unless thisfeature is turned off.</p><p>IC does parenthesis-balance-highlighting when the cursor is placedto the right of anyright parenthesis, bracket, or brace.</p><p><!----><a name="The_main_Function"></a><font size="+2"><b>The <font face="Courier" color="blue">main()</font> Function</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>After functions have been downloaded to a board, they can be invokedfrom IC so long asthe board is connected. If one of the functions is named <font face="Courier">main()</font>, it can be run directlyfrom the interface as noted earlier, and otherwise will be runautomatically when theboard is reset.</p><p>Note: to reset the Handy Board without running the <font face="Courier">main()</font> function (for instance, whenhooking the board back to the computer), hold down the boarentry.d's <b>Start</b>button whileactivating the board. The board will then reset without running <font face="Courier">main()</font>.</p><p><!----><a name="IC_versus_Standard_C"></a><font size="+3"><b>IC versusStandard C</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The IC programming language is based loosely on ANSI C. However,there are majordifferences.</p><p>Many of these differences arise from the desire to have IC be"safer" than standard C. Forinstance, in IC, array bounds are checked at run time; for this reason,arrays cannot beconverted to pointers in IC. Also, in IC, pointer arithmetic is notallowed.</p><p>Other differences are due to the desire that the IC runtime be smalland efficient. Forinstance, the IC <a href="#printf"><font face="Courier" color="purple">printf</font></a>function does not understand many of the more exoticformatting options specified by ANSI C.</p><p>Yet other differences are due to the desire that IC be simpler thanstandard C. This is thereason for the global scope of all declarations.</p><p>In the rest of this document, when we refer to "C", the statementapplies to both IC andstandard C. When we wish to specify one or the other, we will refer toeither "IC" or"standard C". When no such qualifiers are present, you should assumethat we are talkingabout IC.</p><p><!----><a name="A_Quick_C_Tutorial"></a><font size="+3"><b>A Quick C Tutorial</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Most C programs consist of function definitions and data structures.Here is a simple Cprogram that defines a single function, called <b>main</b>.</p><pre><font color="darkgreen">/* <i>Simple example<br>     IC Programmer's Manual</i>     */</font>  <font color="blue">void</font> main()<br>  {<br>      <font color="blue">printf</font>(<font color="red">"Hello, world!\n"</font>); <font color="darkgreen">// <i>Something simple</i></font>  }</pre>The expression<table>  <tbody>    <tr>      <td>      <dl>        <dd><font face="Courier">/* &lt;</font><i>text</i><font face="Courier">&gt; */</font></dd>      </dl>      </td>    </tr>  </tbody></table>forms a <i>multi-line</i> or <i>bracketed comment</i>. In contrast,text that starts with"<font face="Courier">//</font>" forms a <i>single line comment</i>,which continues only to the end of the line.Comments are ignored by IC when the program is compiled.<p><a name="return_type"></a>All functions must have a return type.Since <b>main</b> does not return a value, it uses<font face="Courier" color="blue">void</font>,the null type, as its return type. Other types include integers (<font face="Courier" color="blue">int</font>) and floating pointnumbers (<font face="Courier" color="blue">float</font>). This <i>functiondeclaration</i> information must precede each functiondefinition.</p><p>Immediately following the function declaration is the function'sname (in this case,<b>main</b>). Next, in parentheses, are any arguments (or inputs) tothe function.<b>main</b> hasnone, but an empty set of parentheses is still required.</p><p>After the function arguments is an open curly-brace {. Thissignifies the start of theactual function code. Curly-braces signify program <i>blocks</i>, orchunks of code.</p><p>Next comes a series of <i>C statements</i>. Statements demand thatsome action be taken. Ourdemonstration program has a single statement, a <font face="Courier" color="purple">printf</font> (formatted print). This willprint the message <b>"Hello, world!"</b> to the LCD display. The <b>\n</b>indicates end-of-line.The <font face="Courier" color="purple">printf</font> statement endswith a semicolon (;). <i>All</i> C statements must be ended by asemicolon. Beginning C programmers commonly make the error of omittingthesemicolon that is required to end each statement.</p><p>The <b>main</b> function is ended by the close curly-brace }.</p><p>Let's look at an another example to learn some more features of C.The following codedefines the function <i>square</i>, which returns the mathematicalsquare of a number.</p><pre><font color="blue">int</font> square(<font color="blue">int</font> n)<br>   {<br>       <font color="blue">return</font>(n * n);<br>   }<br></pre>The function is declared as type <font face="Courier" color="blue">int</font>,which means that it will return an integer value.<p>Next comes the function named <b>square</b>, followed by itsargument list in parentheses.square has one argument, <b>n</b>, which is an integer. Notice howdeclaring the type of theargument is done similarly to declaring the type of the function.</p><p>When a function has arguments declared, those argument variables arevalid within the"scope" of the function (i.e., they only have meaning within thefunction's own code).Other functions may use the same variable names independently.</p><p><a name="return_statement"></a>The code for <b>square</b> iscontained within the set of curly braces. In fact, it consists of asingle statement: the <font face="Courier" color="blue">return</font>statement. The<font face="Courier" color="blue">return</font> statement exits thefunction andreturns the value of the C <i>expression</i> that follows it (in thiscase "<b>n * n</b>").</p><p>Except where grouped by parentheses, expressions are evaluatedaccording to a set ofprecedence rules associated with the various operations within theexpression. In thiscase, there is only one operation (multiplication), signified by the "<b>*</b>",so precedence isnot an issue.</p><p>Let's look at an example of a function that performs a function callto the square program.</p><pre><font color="blue">float</font> hypotenuse(<font color="blue">int</font> a, <font color="blue">int</font> b)<br>   {<br>       <font color="blue">float</font> h;<br>       h = <font color="purple">sqrt</font>((<font color="blue">float</font>)(square(a) + square(b)));<br>       <font color="blue">return</font>(h);<br>   }<br></pre>This code demonstrates several more features of C. First, notice thatthe floating pointvariable <b>h</b> is defined at the beginning of the <b>hypotenuse</b>function. In general, whenevera new program block (indicated by a set of curly braces) is begun, newlocal variablesmay be defined.<p>The value of <b>h</b> is set to the result of a call to the <font face="Courier" color="purple">sqrt</font> function. It turns out that<font face="Courier" color="purple">sqrt</font> is abuilt-in IC function that takes a floating point number as itsargument.</p><p>We want to use the <b>square</b> function we defined earlier, whichreturns its result as aninteger. But the sqrt function requires a floating point argument. Weget around thistype incompatibility by coercing the integer sum <b>(square(a) +square(b))</b> into afloat by preceding it with the desired type, in parentheses. Thus, theinteger sum ismade into a floating point number and passed along to <font face="Courier" color="purple">sqrt</font>.</p><p>The <b>hypotenuse</b> function finishes by returning the value of <b>h</b>.</p><p>This concludes the brief C tutorial.</p><p><!----><a name="Data_Objects"></a><font size="+3"><b>Data Objects</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Variables and constants are the basic data objects in a C program.Declarations list thevariables to be used, state what type they are, and may set theirinitial value.</p><p><!----><a name="Variables"></a><font size="+2"><b>Variables</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Variable names are case-sensitive. The underscore character isallowed and is often usedto enhance the readability of long variable names. C keywords like <font face="Courier" color="blue">if</font>,<font face="Courier" color="blue">while</font>, etc. maynot be used as variable names.</p><p>Functions and global variables may not have the same name. Inaddition, if a localvariable is named the same as a function or a global variable, thelocal use takesprecedence; ie., use of the function or global variable is preventedwithin the scope of thelocal variable.</p><dl>  <dd><!---->    <a name="Declaration"></a><font size="+1"><b>Declaration</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    <p>In C, variables can be declared at the top level (outside of anycurly braces) or at the startof each block (a functional unit of code surrounded by curly braces).In general, avariable declaration is of the form:    <table>      <tbody>        <tr>          <td><font face="Times"></font>          <dl>            <dd><font face="Times"><i>&lt;type&gt;&nbsp;&nbsp;&lt;variable-name&gt;</i>; or </font></dd>            <dd><font face="Times"><i>&lt;type&gt;&nbsp;&nbsp;&lt;variable-name&gt;=&lt;initialization-data&gt;</i>;</font></dd>          </dl>          </td>        </tr>      </tbody>    </table>In IC, <i>&lt;<a href="#Data%20Types">type</a>&gt;</i> can be <font face="Courier" ,="" color="blue">int</font>,    <font face="Courier" ,="" color="blue">long</font>, <font face="Courier" ,="" color="blue">float</font>,    <font face="Courier" ,="" color="blue">char</font>, or <font face="Courier" ,="" color="blue">struct</font> <i>&lt;struct-name&gt;</i>,anddetermines the <i>primary type</i> of the variable declared. This formchanges somewhat whendealing with pointer and array declarations, which are explained in alater section, but ingeneral this is the way you declare variables.    </p>    <p><!---->    <a name="Local_and_Global_Scopes"></a><font size="+1"><b>Local andGlobal Scopes</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>If a variable is declared within a function, or as an argumentto a function, its binding is    <i>local</i>, meaning that the variable has existence only withinthat function definition.If a variable is declared outside of a function, it is a <i>global</i>variable. It is defined for allfunctions, including functions which are defined in files other thanthe one in which theglobal variable was declared.    </p>    <p><!---->    <a name="Variable_Initialization"></a><font size="+1"><b>VariableInitialization</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>Local and global variables can be initialized to a value whenthey are declared. If noinitialization value is given, the variable is initialized to zero.    </p>    <p>All global variable declarations must be initialized to constantvalues. Local variablesmay be initialized to the value of arbitrary expressions including anyglobal variables,function calls, function arguments, or local variables which havealready been initialized.    </p>    <p>Here is a small example of how initialized declarations areused.    </p>    <pre>   <font color="blue">int</font> i=50;     <font color="darkgreen">/* <i>declare i as global integer; initial value 50</i> */</font>   <font color="blue">long</font> j=100L;  <font color="darkgreen">/* <i>declare j as global long; initial value 100</i> */</font>   <font color="blue">int</font> foo()<br>   {<br>     <font color="blue">int</font> x;      <font color="darkgreen">/* <i>declare x as local integer; initial value 0</i> */</font>     <font color="blue">long</font> y=j;   <font color="darkgreen">/* <i>declare y as local integer; initial value j</i> */</font>   }    </pre>Local variables are initialized whenever the function containing themis executed.Global variables are initialized whenever a reset condition occurs.Reset conditions occurwhen:    <table>      <tbody>        <tr>          <td>          <ol>            <font face="Times"><li>Code is downloaded;            </li>            <li>The <b>main()</b> procedure is run;            </li>            <li>System hardware reset occurs.</li>            </font>          </ol>          </td>        </tr>      </tbody>    </table>    <p><!----><a name="Persistent_Global_Variables"></a>    <font size="+1"><b>Persistent Global Variables</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>A special persistent form of global variable, has beenimplemented for IC. A persistentglobal variable may be initialized just like any other global variable,but its value is onlyinitialized when the code is downloaded and not on any other resetconditions. If noinitialization information is included for a persistent variable, itsvalue will be initializedto zero on download, but left unchanged on all other reset conditions.    </p>    <p>To make a persistent global variable, prefix the type specifierwith the keyword    <font face="Courier" color="blue">persistent</font>. For example,the statement    </p>    <pre>   <font color="blue">persistent int</font> i=500;<br></pre>creates a global integer called <b>i</b> with the initial value <b>500</b>.    <p>Persistent variables keep their state when the board is turned off andon, when <b>main</b> isrun, and when system reset occurs. Persistent variables will lose theirstate when code isdownloaded as a result of loading or unloading a file. However, it ispossible to read thevalues of your persistent variables in IC if you are still running thesame IC session fromwhich the code was downloaded. In this manner you could read the finalvalues ofcalibration persistent variables, for example, and modify the initialvalues given to thosepersistent variables appropriately.    </p>    <p>Persistent variables were created with two applications in mind:    <table>      <tbody>        <tr>          <td><font face="Times">          <ul>            <li>Calibration and configuration values that do not needto be re-calculated on everyreset condition.            </li>            <li>Robot learning algorithms that might occur over aperiod when the robot is turnedon and off.            </li>          </ul>          </font></td>        </tr>      </tbody>    </table>    </p>  </dd></dl><!----><a name="Constants"></a><font size="+2"><b>Constants</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p><!----></p><dl>  <dd><a name="Integer_Constants"></a>    <font size="+1"><b>Integer Constants</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    <p>Integers constants may be defined in decimal integer format(e.g., <b>4053</b> or <b>-1</b>),hexadecimal format using the "<b>0x</b>" prefix (e.g., <b>0x1fff</b>),and a non-standard but usefulbinary format using the "<b>0b</b>" prefix (e.g., <b>0b1001001</b>).Octal constants using the zeroprefix are not supported.    </p>    <p><!---->    <a name="Long_Integer_Constants"></a><font size="+1"><b>LongInteger Constants</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>Long integer constants are created by appending the suffix "<b>l</b>"or "<b>L</b>" (upper- or lower-case alphabetic L) to a decimal integer. For example, <b>0L</b> is thelong zero. Either the upperor lower-case "<b>L</b>" may be used, but upper-case is the conventionfor readability.    </p>    <p><!---->    <a name="Floating_Point_Constants"></a><font size="+1"><b>FloatingPoint Constants</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>Floating point numbers may use exponential notation (e.g., "<b>10e3</b>"or "<b>10E3</b>") or maycontain a decimal period. For example, the floating point zero can begiven as "<b>0.</b>","<b>0.0</b>", or "<b>0E1</b>", but not as just "<b>0</b>". <i>Sincethe board has no floating point hardware,floating point operations are much slower than integer operations, andshould be usedsparingly.</i>    </p>    <p><!---->    <a name="Characters_and_String_Constants"></a><font size="+1"><b>Charactersand String Constants</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>Quoted characters return their ASCII value (e.g., '<b>x</b>').    </p>    <p>Character string constants are defined with quotation marks,e.g.,    <font face="Courier" color="red">"This is a character string."</font>.    </p>    <p><!---->    <a name="NULL"></a><font size="+1"><b><font face="Courier">NULL</font></b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>The special constant <b>NULL</b> has the value of zero and canbe assigned to and compared topointer or array variables (which will be described in later sections).In general, youcannot convert other constants to be of a pointer type, so there aremany times when    <b>NULL</b> can be useful.    </p>    <p>For example, in order to check if a pointer has been initializedyou could compare itsvalue to <b>NULL</b> and not try to access its contents if it was <b>NULL</b>.Also, if you had a defineda linked list type consisting of a value and a pointer to the nextelement, you could lookfor the end of the list by comparing the next pointer to <b>NULL</b>.    </p>  </dd></dl><!----><a name="Data_Types"></a><font size="+2"><b>Data Types</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>IC supports the following data types:</p><p><!----></p><dl>  <dd><a name="16-bit_Integers"></a>    <font size="+1"><b>16-bit Integers</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    <p>16-bit integers are signified by the type indicator <font face="Courier" color="blue">int</font>. They are signed integers, andmaybe valued from -32,768 to +32,767 decimal.    </p>    <p><!---->    <a name="32-bit_Integers"></a><font size="+1"><b>32-bit Integers</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>32-bit integers are signified by the type indicator <font face="Courier" color="blue">long</font>. They are signed integers, andmay be valued from -2,147,483,648 to +2,147,483,647 decimal.    </p>    <p><!---->    <a name="32-bit_Floating_Point_Numbers"></a><font size="+1"><b>32-bitFloating Point Numbers</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>Floating point numbers are signified by the type indicator <font face="Courier" color="blue">float</font>. They haveapproximately seven decimal digits of precision and are valued fromabout 10^-38 to10^38.    </p>    <p><!---->    <a name="8-bit_Characters"></a><font size="+1"><b>8-bit Characters</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>Characters are an 8-bit number signified by the type indicator <font face="Courier" color="blue">char</font>. A character's valuetypically represents a printable symbol using the standard ASCIIcharacter code, but thisis not necessary; characters can be used to refer to arbitrary 8-bitnumbers.    </p>    <p><!---->    <a name="Pointers"></a></p>    <p><font size="+1"><b>Pointers</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>IC pointers are 16-bit numbers which represent locations in memory.Values in memorycan be manipulated by calculating, passing and <i>dereferencing</i>pointers representing thelocation where the information is stored.    </p>    <p><!---->    <a name="Arrays"></a></p>    <p><font size="+1"><b>Arrays</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>Arrays are used to store homogenous lists of data (meaning that all theelements of anarray have the same type). Every array has a length which is determinedat the time thearray is declared. The data stored in the elements of an array can beset and retrieved inthe same manner as for other variables.    </p>    <p><!---->    <a name="Structures"></a><font size="+1"><b>Structures</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font>    </p>    <p>Structures are used to store non-homogenous but related sets ofdata. Elements of astructure are referenced by name instead of number and may be of anysupported type.    </p>    <p>Structures are useful for organizing related data into acoherent format, reducing thenumber of arguments passed to functions, increasing the effectivenumber of valueswhich can be returned by functions, and creating complex datarepresentations such asdirected graphs and linked lists.    </p>  </dd></dl><!----><a name="PointersM"></a><font size="+2"><b>Pointers</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>The address where a value is stored in memory is known as thepointer to that value. It isoften useful to deal with pointers to objects, but great care must betaken to insure that thepointers used at any point in your code really do point to validobjects in memory.</p><p>Attempts to refer to invalid memory locations could corrupt yourmemory. Mostcomputing environments that you are probably used to return helpfulmessages like'Segmentation Violation' or 'Bus Error' on attempts to access illegalmemory.However, you won't have this safety net on the board you are connectingto. Invalidpointer dereferencing is very likely to go undetected, and will likelyrender invalid yourdata, your program, or even the pcode interpreter.</p><p><!----><a name="Pointer_Safety"></a><font size="+1"><b>Pointer Safety</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>In past versions of IC, you could not return pointers from functionsor have arrays ofpointers. In order to facilitate the use of structures, these featureshave been added to thecurrent version. With this change, the number of opportunities tomisuse pointers haveincreased. However, if you follow a few simple precautions you shoulddo fine.</p><p>First, you should always check that the value of a pointer is notequal to <b>NULL</b> (a specialzero pointer) before you try to access it. Variables which are declaredto be pointers areinitialized to <b>NULL</b>, so many uninitialized values could becaught this way.</p><p>Second, you should never use a pointer to a local variable in amanner which could causeit to be accessed after the function in which it was declaredterminates. When a functionterminates the space where its values were being stored is recycled.Therefore not onlymay dereferencing such pointers return incorrect values, but assigningto those addressescould lead to serious data corruption. A good way to prevent this is tonever return theaddress of a local variable from the function which declares it andnever store thosepointers in an object which will live longer than the function itself(a global pointer,array, or <font face="Courier">struct</font>). Global variables andvariables local to main will not move oncedeclared and their pointers can be considered to be secure.</p><p>The type checking done by IC will help prevent many mishaps, but itwill not catch allerrors, so be careful.</p><p><!----><a name="Pointer_Declaration_and_Use"></a><font size="+1"><b>PointerDeclaration and Use</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>A variable which is a pointer to an object of a given type isdeclared in the same manneras a regular object of that type, but with an extra * in front of thevariable name.</p><p>The value stored at the location the pointer refers to is accessedby using the * operatorbefore the expression which calculates the pointer. This process isknown asdereferencing.</p><p>The address of a variable is calculated by using the <b>&amp;</b>operator before that variable, arrayelement, or structure element reference.</p><p>There are two main differences between how you would use a variableof a given typeand a variable declared as a pointer to that type.</p><p>For the following explanation, consider <b>X</b> and <b>Xptr</b>as defined as follows:</p><pre>   <font color="blue">long</font> X; <font color="blue">long</font> *Xptr;<br></pre><ul>  <li>Space Allocation -- Declaring an object of a given type, as <b>X</b>is of type    <font face="Courier" color="blue">long</font>,allocates the space needed to store that value. Because an IC longtakes four bytesof memory, four bytes are reserved for the value of <b>X</b> tooccupy. However, apointer like <b>Xptr</b> does not have the same amount of spaceallocated for it that isneeded for an object of the type it points to. Therefore it can onlysafely refer tospace which has already been allocated for globals (in a specialsection ofmemory reserved for globals) or locals (temporary storage on thestack).  </li>  <li>Initial Value -- It is always safe to refer to a non-pointertype, even if it hasn'tbeen initialized. However pointers have to be specifically assigned tothe addressof legally allocated space or to the value of an already initializedpointer beforethey are safe to use.  </li></ul>So, for example, consider what would happen if the first two statementsafter <b>X</b> and <b>Xptr</b>were declared were the following:<pre>   X=50L; *Xptr=50L;<br></pre>The first statement is valid: it sets the value of <b>X</b> to <b>50L</b>.The second statement would bevalid if <b>Xptr</b> had been properly initialized, but in this caseit has not. Therefore, thisstatement would corrupt memory.<p>Here is a sequence of commands you could try which illustrate howpointers and the *and &amp; operators are used. It also shows that once a pointer hasbeen set to point at a placein memory, references to it actually share the same memory as theobject it points to:</p><pre>   X=50L;               <font color="darkgreen">/* <i>set the memory allocated for X to 50</i> */</font>   Xptr=&amp;X;             <font color="darkgreen">/* <i>set Xptr to point to memory address of X</i> */</font>   <font color="purple">printf</font>(<font color="red">"%d "</font>,*Xptr); <font color="darkgreen">/* <i>dereference Xptr; value at address is 50</i> */</font>   X=100L;              <font color="darkgreen">/* <i>set X to the value 100</i> */</font>   <font color="purple">printf</font>(<font color="red">"%d "</font>,*Xptr); <font color="darkgreen">/* <i>dereference again; value is now 100</i> */</font>   *Xptr=200L;          <font color="darkgreen">/* <i>set value at address given by Xptr to 200</i> */</font>   <font color="purple">printf</font>(<font color="red">"%d\n"</font>,X);    <font color="darkgreen">/* <i>check that the value of X changed to 200</i> */</font></pre><p><!----><a name="Passing_Pointers_as_Arguments"></a><font size="+1"><b>Passing Pointers as Arguments</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Pointers can be passed to functions and functions can change thevalues of the variablesthat are pointed at. This is termed <i>call-by-reference</i>; areference, or pointer, to a variableis given to the function that is being called. This is in contrast to <i>call-by-value</i>,thestandard way that functions are called, in which the value of avariable is given the tofunction being called.</p><p>The following example defines an <b>average_sensor</b> functionwhich takes a portnumber and a pointer to an integer variable. The function will averagethe sensor andstore the result in the variable pointed at by <b>result</b>.</p><p>Prefixing an argument name with * declares that the argument is apointer.</p><pre>   <font color="blue">void</font> average_sensor(<font color="blue">int</font> port, <font color="blue">int</font> *result)<br>   {<br>      <font color="blue">int</font> sum = 0;<br>      <font color="blue">int</font> i;<br>      <font color="blue">for</font> (I = 0; I &lt; 10; i++) sum += <font color="purple">analog</font>(port);<br>      *result =  sum/10;<br>   }<br></pre>Notice that the function itself is declared as a <font face="Courier" color="blue">void</font>. It does not need to return anything,because it instead stores its answer in the memory location given bythe pointer variablethat is passed to it.<p>The pointer variable is used in the last line of the function. Inthis statement, the answersum/10 is stored at the location pointed at by result. Notice that the* is used to assign avalue to the location pointed by result.</p><p><!----><a name="Returning_Pointers_from_Functions"></a><font size="+1"><b>ReturningPointers from Functions</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Pointers can also be returned from functions. Functions are definedto return pointers bypreceeding the name of the function with a star, just like any othertype of pointerdeclaration.</p><pre>   <font color="blue">int</font> right,left;<br>   <font color="blue">int</font> *dirptr(<font color="blue">int</font> dir)<br>   {<br>       <font color="blue">if</font> (dir==0) {<br>         <font color="blue">return</font>(&amp;right);<br>       }<br>       <font color="blue">if</font> (dir==1) {<br>          <font color="blue">return</font>(&amp;left);<br>       }<br>       <font color="blue">return</font>(NULL);<br>   }<br></pre>The function <b>dirptr</b> returns a pointer to the global <b>right</b>when its argument <b>dir</b> is 0, apointer to <b>left</b> when its argument is 1, and <b>NULL"</b> ifits argument is other than 0 or 1.<p><!----><a name="Arrays"></a><font size="+2"><b>Arrays</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>IC supports arrays of characters, integers, long integers,floating-point numbers,structures, pointers, and array pointers (multi-dimensional arrays).While unlike regular Carrays in a number of respects, they can be used in a similar manner.The main reasonsthat arrays are useful are that they allow you to allocate space formany instances of agiven type, send an arbitrary number of values to functions, andprovide the means foriterating over a set of values.</p><p>Arrays in IC are different and incompatible with arrays in otherversions of C. Thisincompatibility is caused by the fact that references to IC arrays arechecked to insurethat the reference is truly within the bounds of that array. In orderto accomplish thischecking in the general case, it is necessary that the size of thearray be stored with thecontents of the array. <i>It is important to remember that an array ofa given type and apointer to the same type are incompatible types in IC, whereas they arelargelyinterchangeable in regular C</i>.</p><p><!----><a name="Declaring_and_Initializing_Arrays"></a><font size="+1"><b>Declaringand Initializing Arrays</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Arrays are declared using square brackets. The following statementdeclares an array often integers:</p><pre>   <font color="blue">int</font> foo[10];<br></pre>In this array, elements are numbered from 0 to 9. Elements are accessedby enclosing theindex number within square brackets: <b>foo[4]</b> denotes the fifthelement of the array foo(since counting begins at zero).<p>Arrays are initialized by default to contain all zero values. Arraysmay also be initializedat declaration by specifying the array elements, separated by commas,within curlybraces. If no size value is specified within the square brackets whenthe array is declaredbut initialization information is given, the size of the array isdetermined by the numberof elements given in the declaration. For example,</p><pre>   <font color="blue">int</font> foo[]= {0, 4, 5, -8,  17, 301};<br></pre>creates an array of six integers, with <b>foo[0]</b> equaling <b>0</b>,<b>foo[1]</b> equaling <b>4</b>, etc.<p>If a size is specified and initialization data is given, the lengthof the initialization datamay not exceed the specified length of the array or an error results.If, on the other hand,you specify the size and provide fewer initialization elements than thetotal length of thearray, the remaining elements are initialized to zero.</p><p>Character arrays are typically text strings. There is a specialsyntax for initializing arraysof characters. The character values of the array are enclosed inquotation marks:</p><pre>   <font color="blue">char</font> string[]= <font color="red">"Hello there"</font>;<br></pre>This form creates a character array called <b>string</b> with theASCII values of the specifiedcharacters. In addition, the character array is terminated by a zero.Because of this zero-termination, the character array can be treated asa string for purposes of printing (forexample). Character arrays can be initialized using the curly bracessyntax, but they willnot be automatically null-terminated in that case. In general, printingof character arraysthat are not null-terminated will cause problems.<p><!----><a name="Passing_Arrays_as_Arguments"></a><font size="+1"><b>PassingArrays as Arguments</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>When an array is passed to a function as an argument, the array'spointer is actuallypassed, rather than the elements of the array. If the function modifiesthe array values, thearray will be modified, since there is only one copy of the array inmemory.</p><p>In normal C, there are two ways of declaring an array argument: asan array or as apointer to the type of the array's elements. In IC array pointers areincompatible withpointers to the elements of an array so such arguments can only bedeclared as arrays.</p><p>As an example, the following function takes an index and an array,and returns the arrayelement specified by the index:</p><pre>   <font color="blue">int</font> retrieve_element(<font color="blue">int</font> index, <font color="blue">int</font> array[])<br>   {<br>       <font color="blue">return</font> array[index];<br>   }<br></pre>Notice the use of the square brackets to declare the argument array asa pointer to anarray of integers.<p>When passing an array variable to a function, you are actuallypassing the value of thearray pointer itself and not one of its elements, so no square bracketsare used.</p><pre>   <font color="blue">void</font> foo()<br>   {<br>       <font color="blue">int</font> array[10];<br>       retrieve_element(3, array);<br>   }<br></pre><!----><a name="Multi-dimensional_Arrays"></a><font size="+1"><b>Multi-dimensionalArrays</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>A two-dimensional array is just like a single dimensional arraywhose elements are one-dimensional arrays. Declaration of a two-dimensional array is asfollows:</p><pre>   <font color="blue">int</font> k[2][3];<br></pre>The number in the first set of brackets is the number of 1-D arrays of <font face="Courier" color="blue">int</font>. The number inthe second set of brackets is the length of each of the 1-D arrays of <font face="Courier" color="blue">int</font>. In this example,<b>k</b> is an array containing two 1-D arrays; <b>k[0]</b> is a 1-Darray of <font face="Courier">color=blue&gt;int</font> of length 3;<b>k[0][1]</b> is an <font face="Courier">color=blue&gt;int</font>.Arrays of with any number of dimensions can be generalized fromthis example by adding more brackets in the declaration.<p><!----><a name="Determining_the_size_of_Arrays_at_Runtime"></a><font size="+1"><b>Determiningthe size of Arrays at Runtime</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>An advantage of the way IC deals with arrays is that you candetermine the size of arraysat runtime. This allows you to do size checking on an array if you areuncertain of itsdimensions and possibly prevent your program from crashing.</p><p><i>Since </i><font face="Courier"><b>_array_size</b></font> <i>isnot a standard C feature, code written using this primitive willonly be able to be compiled with IC</i>.</p><p>The <b>_array_size</b> primitive returns the size of the arraygiven to it regardless of thedimension or type of the array. Here is an example of declarations andinteraction withthe <b>_array_size</b> primitive:</p><pre>   <font color="blue">int</font> i[4]={10,20,30};<br>   <font color="blue">int</font> j[3][2]={{1,2},{2,4},{15}};<br>   <font color="blue">int</font> k[2][2][2];<br>   _array_size(i);    <font color="darkgreen">/* <i>returns 4</i> */</font>   _array_size(j);    <font color="darkgreen">/* <i>returns 3</i> */</font>   _array_size(j[0]); <font color="darkgreen">/* <i>returns 2</i> */</font>   _array_size(k);    <font color="darkgreen">/* <i>returns 2</i> */</font>   _array_size(k[0]); <font color="darkgreen">/* <i>returns 2</i> */</font></pre><!----><a name="Uploading_Arrays"></a><font size="+1"><b>Uploading Arrays</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>When an executing program is paused or has finished, IC can uploadthe values storedin any global array via the serial port. This permits collecting andrecording datafor purposes such as experimentation or calibration.</p><p>The IC upload array capability is accessed using the tools tab. Whenupload array isactivated, it lists all globally declared arrays. When an array isselected, it isopened in a (modal) view window. The array can be copied to theclipboard, or savedto a TXT or CSV (comma separated values) file for import to analysissoftware.</p><p><!----><a name="Structures2"></a><font size="+2"><b>Structures</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Structures are used to store non-homogenous but related sets ofdata. Elements of astructure are referenced by name instead of number and may be of anysupported type.Structures are useful for organizing related data into a coherentformat, reducing thenumber of arguments passed to functions, increasing the effectivenumber of valueswhich can be returned by functions, and creating complex datarepresentations such asdirected graphs and linked lists.</p><p>The following example shows how to define a structure, declare avariable of structuretype, and access its elements.</p><pre>   <font color="blue">struct</font> foo<br>   {<br>       <font color="blue">int</font> i;<br>       <font color="blue">int</font> j;<br>   };<br>   <font color="blue">struct</font> foo f1;<br>   <font color="blue">void</font> set_f1(<font color="blue">int</font> i,<font color="blue">int</font> j)<br>   {<br>       f1.i=i;<br>       f1.j=j;<br>   }<br>   <font color="blue">void</font> get_f1(<font color="blue">int</font> *i,<font color="blue">int</font> *j)<br>   {<br>       *i=f1.i;<br>       *j=f1.j;<br>   }<br></pre>The first part is the structure definition. It consists of the keyword<font face="Courier" color="blue">struct</font>, followed bythe name of the structure (which can be any valid identifier), followedby a list of namedelements in curly braces. This definition specifies the structure ofthe type <font face="Courier" color="blue">struct</font> <b>foo</b>.Once there is a definition of this form, you can use the type <font face="Courier" color="blue">struct</font> <b>foo</b> just like anyother type. The line<pre>    <font color="blue">struct</font> foo f1;<br></pre>is a global variable declaration which declares the variable <b>f1</b>to be of type <font face="Courier" color="blue">struct</font><b>foo</b>.<p>The dot operator is used to access the elements of a variable ofstructure type. In thiscase, <b>f1.i</b> and <b>f1.j</b> refer to the two elements of <b>f1</b>.You can treat the quantities <b>f1.i</b>and <b>f1.j</b> just as you would treat any variables of type <font face="Courier" color="blue">int</font> (the type of the elements wasdefined in the structure declaration at the top to be <font face="Courier" color="blue">int</font>).</p><p>Pointers to structure types can also be used, just like pointers toany other type. However,with structures, there is a special short-cut for referring to theelements of the structurepointed to.</p><pre>   <font color="blue">struct</font> foo *fptr;<br>   <font color="blue">void</font> main()<br>   {<br>       fptr=&amp;f1;<br>       fptr-&gt;i=10;<br>       fptr-&gt;j=20;<br>   }<br></pre>In this example, <b>fptr</b> is declared to be a pointer to type <font face="Courier" color="blue">struct</font> <b>foo</b>. In main, it isset topoint to the global <b>f1</b> defined above. Then the elements of thestructure pointed to by <b>fptr</b>(in this case these are the same as the elements of <b>f1</b>), areset. The arrow operator is usedinstead of the dot operator because fptr is a pointer to a variable oftype <font face="Courier" color="blue">struct</font> <b>foo</b>. Notethat <b>(*fptr).i</b> would have worked just as well as <b>fptr<font face="Courier">-&gt;</font>i</b>, but it would have beenclumsier.<p>Note that only pointers to structures, not the structuresthemselves, can be passed to orreturned from functions.</p><p><!----><a name="Complex_Initialization_examples"></a><font size="+2"><b>ComplexInitialization examples</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Complex types -- arrays and structures -- may be initialized upondeclaration with asequence of constant values contained within curly braces and separatedby commas.</p><p>Arrays of character may also be initialized with a quoted string ofcharacters.</p><p>For initialized declarations of single dimensional arrays, thelength can be left blank anda suitable length based on the initialization data will be assigned toit. <i>Multi-dimensionalarrays must have the size of all dimensions specified when the array isdeclared</i>. If alength is specified, the initialization data may not overflow thatlength in any dimensionor an error will result. However, the initialization data may beshorter than the specifiedsize and the remaining entries will be initialized to 0.</p><p>Following is an example of legal global and local variableinitializations:</p><pre>   <font color="darkgreen">/* <i>declare many globals of various types</i> */</font>   <font color="blue">int</font> i=50;<br>   <font color="blue">int</font> *ptr=NULL;<br>   <font color="blue">float</font> farr[3]={ 1.2, 3.6, 7.4 };<br>   <font color="blue">int</font> tarr[2][4]={ { 1, 2, 3, 4 }, { 2, 4, 6, 8} };<br>   <font color="blue">char</font> c[]=<font color="red">"Hi there how are you?"</font>;<br>   <font color="blue">char</font> carr[5][10]={<font color="red">"Hi"</font>,<font color="red">"there"</font>,<font color="red">"how"</font>,<font color="red">"are"</font>,<font color="red">"you"</font>};<br>   <font color="blue">struct</font> bar<br>   {<br>      <font color="blue">int</font> i;<br>      <font color="blue">int</font> *p;<br>      <font color="blue">long</font> j;<br>   } b={5, NULL, 10L};<br>   <font color="blue">struct</font> bar barr[2] = { { 1, NULL, 2L }, { 3 } };<br>   /* declare locals of various types */<br>   <font color="blue">int</font> foo()<br>   {<br>      <font color="blue">int</font> x;             <font color="darkgreen">/* <i>local variable x with initial value 0</i> */</font>      <font color="blue">int</font> y= tarr[0][2]; <font color="darkgreen">/* <i>local variable y with initial value 3</i> */</font>      <font color="blue">int</font> *iptr=&amp;i;      <font color="darkgreen">/* <i>local pointer to integer<br>                            which points to the global i</i> */</font>      <font color="blue">int</font> larr[2]={10,20};  <font color="darkgreen">/* <i>local array larr<br>                               with elements 10 and 20</i> */</font>      <font color="blue">struct</font> bar lb={5,NULL,10L};  <font color="darkgreen">/* <i>local variable of type<br>                                      struct bar with i=5 and j=10 </i>*/</font>      <font color="blue">char</font> lc[]=carr[2];    <font color="darkgreen">/* <i>local string lc with<br>                               initial value "how"</i> */</font>      ...   }</pre><!----><a name="Statements_and_Expressions"></a><font size="+3"><b>Statementsand Expressions</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>Operators act upon objects of a certain type or types and specifywhat is to be done tothem. Expressions combine variables and constants to create new values.Statements areexpressions, assignments, function calls, or control flow statementswhich make up Cprograms.</p><p><!----><a name="Operators"></a><font size="+2"><b>Operators</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Each of the data types has its own set of operators that determinewhich operations maybe performed on them.</p><p><!----><a name="Integer_Operations"></a><font size="+2"><b>Integer Operations</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The following operations are supported on integers:</p><ul>  <li><b>Arithmetic</b>. addition <font face="Courier">+</font>,subtraction <font face="Courier">-</font>, multiplication <font face="Courier">*</font>, division <font face="Courier">/</font>. </li>  <li><b>Comparison</b>. greater-than <font face="Courier">&gt;</font>,less-than <font face="Courier">&lt;</font>, equality <font face="Courier">==</font>, greater-than-equal <font face="Courier">&gt;=</font>,less-than-equal <font face="Courier">&lt;=</font>. </li>  <li><b>Bitwise Arithmetic</b>. bitwise-OR <font face="Courier">|</font>,bitwise-AND <font face="Courier">&amp;</font>, bitwise-exclusive-OR <font face="Courier">^</font>, bitwise-NOT <font face="Courier">~</font>. </li>  <li><b>Boolean Arithmetic</b>. logical-OR <font face="Courier">||</font>,logical-AND <font face="Courier">&amp;&amp;</font>, logical-NOT <font face="Courier">!</font>. <br>When a C statement uses a boolean value (for example, <font face="Courier" color="blue">if</font>), it takes the integer zero asmeaning false, and any integer other than zero as meaning true. Theboolean operators return zero for false and one for true. Booleanoperators <font face="Courier">&amp;&amp;</font> and <font face="Courier">||</font> will stop executing as soon as the truth ofthe final expression is determined. For example, in the expression <font face="Courier">a &amp;&amp; b</font>, if <font face="Courier">a</font>is false, then <font face="Courier">b</font> does not need to beevaluated because the result must be false. The <font face="Courier">&amp;&amp;</font>operator therefore will not evaluate <font face="Courier">b</font>.</li></ul><!----><a name="Long_Integers"></a><font size="+2"><b>Long Integers</b></font>&nbsp;&nbsp;<font size="1"> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></font><p>A subset of the operations implemented for integers are implementedfor long integers:arithmetic addition +, subtraction -, and multiplication *, and theinteger comparisonoperations. Bitwise and boolean operations and division are notsupported.</p><p><!----><a name="Floating_Point_Numbers"></a><font size="+2"><b>Floating PointNumbers</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>IC uses a package of public-domain floating point routinesdistributed by Motorola. Thispackage includes arithmetic, trigonometric, and logarithmic functions.Since floatingpoint operations are implemented in software, they are much slower thanthe integeroperations; we recommend against using floating point if you areconcerned aboutperformance.</p><p>The following operations are supported on floating point numbers:<table>  <tbody>    <tr>      <td><font face="Times">      <ul>        <li><b>Arithmetic</b>. addition <font face="Courier">+</font>,subtraction <font face="Courier">-</font>, multiplication <font face="Courier">*</font>, division <font face="Courier">/</font>.        </li>        <li><b>Comparison</b>. greater-than <font face="Courier">&gt;</font>,less-than <font face="Courier">&lt;</font>, equality <font face="Courier">==</font>, greater-than-equal <font face="Courier">&gt;=</font>,less-than-equal <font face="Courier">&lt;=</font>.        </li>        <li><b>Built-in Math Functions</b>. A set of trigonometric,logarithmic, and exponentialfunctions is supported. For details, go to the          <a href="#Library%20Function%20Descriptions">Library FunctionDescriptions</a>.These functions are included among those itemized as "Math" functions.</li>      </ul>      </font></td>    </tr>  </tbody></table><!----><a name="Characters"></a><font size="+2"><b>Characters</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Characters are only allowed in character arrays. When a cell of thearray is referenced, itis automatically coerced into a integer representation for manipulationby the integeroperations. When a value is stored into a character array, it iscoerced from a standard 16-bit integer into an 8-bit character (by truncating the upper eightbits).</p><p><!----><a name="Assignment_Operators_and_Expressions"></a><font size="+3"><b>AssignmentOperators and Expressions</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The basic assignment operator is <font face="Courier">=</font>. Thefollowing statement adds 2 to the value of <font face="Courier">a</font>.</p><pre>   a = a + 2;<br></pre>The abbreviated form<pre>   a += 2;<br></pre>could also be used to perform the same operation.All of the following binary operators can be used in this fashion:<pre>   +   -   *   /   %   &lt;&lt;   &gt;&gt;   &amp;   ^   |<br></pre><!----><a name="Increment_and_Decrement_Operators"></a><font size="+3"><b>Incrementand Decrement Operators</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>The increment operator "<font face="Courier">++</font>" incrementsthe named variable. For example, theconstruction "<font face="Courier">a++</font>" is equivalent to "<font face="Courier">a= a+1</font>" or "<font face="Courier">a+= 1</font>".A statement that uses an increment operator has a value. For example,the statement</p><pre>   a= 3; <font color="purple">printf</font>(<font color="red">"a=%d a+1=%d\n"</font>, a, ++a);<br></pre>will display the text "<font face="Courier">a=3 a+1=4</font>".If the increment operator comes after the named variable, then thevalue of the statementis calculated after the increment occurs. So the statement<pre>   a= 3; <font color="purple">printf</font>(<font color="red">"a=%d a+1=%d\n"</font>, a, a++);<br></pre>would display "<font face="Courier">a=3 a+1=3</font>" but would finishwith a set to 4.The decrement operator "<font face="Courier">--</font>" is used in thesame fashion as the increment operator.<p><!----><a name="Data_Access_Operators"></a><font size="+3"><b>Data AccessOperators</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p><b><font face="Courier">&amp;</font></b><table>  <tbody>    <tr>      <td><font face="Times">&nbsp;</font>      <dl>        <dd><font face="Times">A single ampersand preceding a variable,an array reference, or a structure elementreference returns a pointer to the location in memory where thatinformation is beingstored. This should not be used on arbitrary expressions as they do nothave a stableplace in memory where they are being stored.</font></dd>      </dl>      </td>    </tr>  </tbody></table><b><font face="Courier">*</font></b><table>  <tbody>    <tr>      <td><font face="Times">&nbsp;</font>      <dl>        <dd><font face="Times">A single * preceeding an expressionwhich evaluates to a pointer returns the valuewhich is stored at that address. This process of accessing the valuestored within apointer is known as <i>dereferencing</i>.</font></dd>      </dl>      </td>    </tr>  </tbody></table><font face="Courier"><b>[</b>&lt;</font><i>expr</i><font face="Courier">&gt;<b>]</b></font><table>  <tbody>    <tr>      <td><font face="Times">&nbsp;</font>      <dl>        <dd><font face="Times">An expression in square braces followingan expression which evaluates to an array(an array variable, the result of a function which returns an arraypointer, etc.) checksthat the value of the expression falls within the bounds of the arrayand referencesthat element.</font></dd>      </dl>      </td>    </tr>  </tbody></table><b><font face="Courier">.</font></b><table>  <tbody>    <tr>      <td><font face="Times">&nbsp;</font>      <dl>        <dd><font face="Times">A dot between a structure variable andthe name of one of its fields returns the valuestored in that field.</font></dd>      </dl>      </td>    </tr>  </tbody></table><b><font face="Courier">-&gt;</font></b><table>  <tbody>    <tr>      <td><font face="Times">&nbsp;</font>      <dl>        <dd><font face="Times">An arrow between a pointer to astructure and the name of one of its fields in thatstructure acts the same as a dot does, except it acts on the structurepointed at by itsleft hand side. Where <b>f</b> is a structure of a type with <b>i</b>as an element name, the twoexpressions <font face="Courier">f.i</font> and <font face="Courier">(&amp;f)-&gt;i</font>are equivalent.</font></dd>      </dl>      </td>    </tr>  </tbody></table></p><p><!----><a name="Precedence_and_Order_of_Evaluation"></a><font size="+3"><b>Precedenceand Order of Evaluation</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The following table summarizes the rules for precedence andassociativity for the C operators.Operators listed earlier in the table have higher precedence; operatorson the same line of the tablehave equal precedence.<table>  <tbody>    <tr>      <td>      <dl>        <dd>          <table border="1">            <tbody>              <tr>                <td align="center"><font face="Times"><b>Operator</b></font></td>                <td>&nbsp; <b><font face="Times">Associativity</font></b><font face="Times"> &nbsp;</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; () []</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; ! ~ ++ -- - (&lt;</font><i>type</i><font face="Courier">&gt;) &nbsp;</font></td>                <td align="center"><font face="Times">right to left</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; * / %</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; + -</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; &lt;&lt; &gt;&gt;</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; &lt; &lt;= &gt; &gt;=</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; == !=</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; &amp;</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; ^</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; |</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; &amp;&amp;</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; ||</font></td>                <td align="center"><font face="Times">right to left</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; = += -=</font> etc.</td>                <td align="center"><font face="Times">right to left</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; ,</font></td>                <td align="center"><font face="Times">left to right</font></td>              </tr>            </tbody>          </table>        </dd>      </dl>      </td>      <td><br>      </td>    </tr>  </tbody></table><!----></p><p><a name="Control_Flow"></a><font size="+3"><b>Control Flow</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>IC supports most of the standard C control structures.</p><p><!----><a name="Statements_and_Blocks"></a><font size="+2"><b>Statements andBlocks</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>A single C statement is ended by a semicolon. A series of statementsmay be groupedtogether into a <i>block</i> using curly braces. Inside a block, localvariables may be defined. Blocks may beused in place of statements in the control flow constructs.</p><p><!----><a name="If-Else"></a><font size="+2"><b>If-Else</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The <font face="Courier" color="blue">if else</font> statement isused to make decisions. The syntax is:</p><pre>   <font color="blue">if</font> (&lt;<font face="Times"><i>expression</i></font>&gt;)<br>       &lt;<font face="Times"><i>statement-1</i></font>&gt;<br>   <font color="blue">else</font>       &lt;<font face="Times"><i>statement-2</i></font>&gt;<br></pre>&lt;<i>expression</i>&gt; is evaluated; if it is not equal to zero(e.g., logic true), then&lt;<i>statement-1</i>&gt; is executed.<p>The <font face="Courier" color="blue">else</font> clause isoptional. If the<font face="Courier" color="blue">if</font> part of the statement didnot execute, and the<font face="Courier" color="blue">else</font> is present, then &lt;<i>statement-2</i>&gt;executes.</p><p><!----><a name="While"></a><font size="+2"><b>While</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The syntax of a <font face="Courier" color="blue">while</font> loopis the following:</p><pre>   <font color="blue">while</font> (&lt;<font face="Times"><i>expression</i></font>&gt;)<br>       &lt;<font face="Times"><i>statement</i></font>&gt;<br></pre><font face="Courier" color="blue">while</font> begins by evaluating &lt;<i>expression</i>&gt;.If it is false, then&lt;<i>statement</i>&gt; is skipped. If itis true, then &lt;<i>statement</i>&gt; is evaluated. Then theexpression is evaluated again, and thesame check is performed. The loop exits when &lt;<i>expression</i>&gt;becomes zero.<p>One can easily create an infinite loop in C using the <font face="Courier" color="blue">while</font> statement:</p><pre>   <font color="blue">while</font> (1)<br>      &lt;<font face="Times"><i>statement</i></font>&gt;<br></pre><p><!----><a name="Do-While"></a><font size="+2"><b>Do-While</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The syntax of a <font face="Courier" color="blue">do</font>-<font face="Courier" color="blue">while</font> loopis the following:</p><pre>   <font color="blue">do</font><br>      &lt;<font face="Times"><i>statement</i></font>&gt;<br>   <font color="blue">while</font> (&lt;<font face="Times"><i>expression</i></font>&gt;);<br></pre><p>The equivalent <font color="blue">while</font> loop would be the following:</p><pre>   &lt;<font face="Times"><i>statement</i></font>&gt;<br>   <font color="blue">while</font> (&lt;<font face="Times"><i>expression</i></font>&gt;)<br>       &lt;<font face="Times"><i>statement</i></font>&gt;<br></pre><p><!----><a name="For"></a><font size="+2"><b>For</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The syntax of a <font face="Courier" color="blue">for</font> loopis the following:</p><pre>   <font color="blue">for</font> (&lt;<font face="Times"><i>expr-1</i></font>&gt;;&lt;<font face="Times"><i>expr-2</i></font>&gt;;&lt;<font face="Times"><i>expr-3</i></font>&gt;)<br>      &lt;<font face="Times"><i>statement</i></font>&gt;<br></pre>The <font face="Courier" color="blue">for</font> construct isequivalent tothe following construct using <font face="Courier" color="blue">while</font>:<pre>   &lt;<font face="Times"><i>expr-1</i></font>&gt;;<br>   <font face="Courier" color="blue">while</font> (&lt;<font face="Times"><i>expr-2</i></font>&gt;)<br>   {<br>      &lt;<font face="Times"><i>statement</i></font>&gt;<br>      &lt;<font face="Times"><i>expr-3</i></font>&gt;;<br>   }<br>   </pre>Typically, &lt;<i>expr-1</i>&gt; is an assignment, &lt;<i>expr-2</i>&gt;is a relational expression, and &lt;<i>expr-3</i>&gt;is an increment or decrement of some manner. For example, the followingcode countsfrom 0 to 99, printing each number along the way:<pre>   <font color="blue">int</font> i;<br>   <font color="blue">for</font> (i = 0; i &lt; 100; i++)<br>       <font color="purple">printf</font>("%d\n", i);<br></pre><p><!----><a name="Switch"></a><font size="+2"><b>Switch</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The syntax of a <font face="Courier" color="blue">switch</font> block is as follows:</p><pre>   <font face="Courier" color="blue">switch</font> (<font face="Courier" color="blue">int</font>)<br>   {<br>       <font face="Courier" color="blue">case</font> <font face="Times"><i>const1</i></font>:<br>           &lt;<font face="Times"><i>statement list1</i></font>&gt;<br>           <font face="Courier" color="blue">break</font>;<br>       <font face="Courier" color="blue">case</font> <font face="Times"><i>const2</i></font>:<br>           &lt;<font face="Times"><i>statement list2</i></font>&gt;<br>           <font face="Courier" color="blue">break</font>;<br>       <font face="Courier" color="blue">default</font>:<br>           &lt;<font face="Times"><i>statement list3</i></font>&gt;<br>   }<br></pre><p>The <font color="blue" face="Courier">switch</font> construct takes an integer variable as input, and compares it to each <font color="blue" face="Courier">case</font> listed.  The first matching <font color="Times"><i>const</i></font> is selected, andexecution begins there.  The <font color="blue" face="Courier">break</font> is optional, and if no break is found then executioncontinues through each following statement.  Also note that each <font color="blue" face="Courier">case</font> has a list of single statements, as opposed to a block enclosed in curly braces.<br><br>Here's an example of how a <font color="blue" face="Courier">switch</font> might be used:</p><pre>   <font face="Courier" color="blue">int</font> i = 1;<br>   <font face="Courier" color="blue">switch</font>(i)<br>   {<br>       <font face="Courier" color="blue">case</font> 0:<br>           <font face="Courier" color="purple">printf</font>(<font face="Courier" color="red">"Case 0\n"</font>);<br>           <font face="Courier" color="blue">break</font>;<br>       <font face="Courier" color="blue">case</font> 1:<br>           <font face="Courier" color="purple">printf</font>(<font face="Courier" color="red">"Case 1\n"</font>);<br>           <font face="Courier" color="blue">break</font>;<br>       <font face="Courier" color="blue">default</font>:<br>           <font face="Courier" color="purple">printf</font>(<font face="Courier" color="red">"Default\n"</font>);<br>   }<br></pre><p>Since <font face="Times"><i>i</i></font> is equal to 1, the text "Case 1" will be printed to the screen.  If <font face="Times"><i>i</i></font> were equal to 0, "Case 0" would be printed.  If <font face="Times"><i>i</i></font> were any number besides 0 or 1, "Default" would be printed.</p><!----><a name="Break"></a><font size="+2"><b>Break</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>Use of the <font face="Courier" color="blue">break</font> statementprovides an early exit from a<font face="Courier" color="blue">while</font>, <font face="Courier" color="blue">do</font>-<font face="Courier" color="blue">while</font> or <font face="Courier" color="blue">for</font> loop.  The break statement can also provide an exit from a <font face="Courier" color="blue">switch</font> block.</p><p><!----><a name="LCD_Screen_Printing"></a><font size="+3"><b>LCD Screen Printing</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>IC has a version of the C function <font face="Courier" color="purple">printf</font> for formatted printing to the LCD screen.</p><p>The syntax of <font face="Courier" color="purple">printf</font> isthe following:</p><pre>   <font color="purple">printf</font>(&lt;<font face="Times"><i>format-string</i></font>&gt;, &lt;<font face="Times"><i>arg-1</i></font>&gt; , ... , &lt;<font face="Times"><i>arg-N</i></font>&gt;);<br></pre>This is best illustrated by some examples.<p><!----><a name="Printing_Examples"></a><font size="+2"><b>Printing Examples</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p><!----><a name="Printing_a_message"></a><font size="+1"><b>Example 1: Printinga message</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">PMIndex</a></font></p><p>The following statement prints a text string to the screen.<table>  <tbody>    <tr>      <td>      <pre>   <font color="purple">printf</font>(<font color="red">"Hello, world!\n"</font>);</pre>      </td>    </tr>  </tbody></table>In this example, the format string is simply printed to the screen.The character <font face="Courier"><b>\n</b></font> at the end of thestring signifies end-of-line. When an end-of-linecharacter is printed, the LCD screen will be cleared when a subsequentcharacter isprinted. Thus, most <font face="Courier" color="purple">printf</font>statements are terminated by a<font face="Courier"><b>\n</b></font>.</p><p><!----><a name="Printing_a_number"></a><font size="+1"><b>Example 2: Printinga number</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The following statement prints the value of the integer variable xwith a brief message.<table>  <tbody>    <tr>      <td>      <pre>   <font color="purple">printf</font>(<font color="red">"Value is %d\n"</font>, x);</pre>      </td>    </tr>  </tbody></table>The special form <font face="Courier"><b>%d</b></font> is used toformat the printing of an integer in decimal format.</p><p><!----><a name="Printing_a_number_in_binary"></a><font size="+1"><b>Example 3:Printing a number in binary</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The following statement prints the value of the integer variable xas a binary number.<table>  <tbody>    <tr>      <td>      <pre>   <font color="purple">printf</font>(<font color="red">"Value is %b\n"</font>, x);</pre>      </td>    </tr>  </tbody></table>The special form <font face="Courier"><b>%b</b></font> is used toformat the printing of an integer in binary format. Only thelow byte of the number is printed.</p><p><!----><a name="Printing_a_floating_point_number"></a><font size="+1"><b>Example4: Printing a floating point number</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The following statement prints the value of the floating pointvariable <font face="Courier">n</font> as a floatingpoint number.<table>  <tbody>    <tr>      <td>      <pre>   <font color="purple">printf</font>(<font color="red">"Value is %f\n"</font>, n);</pre>      </td>    </tr>  </tbody></table>The special form <font face="Courier"><b>%f</b></font> is used toformat the printing of floating point number.</p><p><!----><a name="Printing_two_numbers_in_hexadecimal_format"></a><font size="+1"><b>Example5: Printing two numbers in hexadecimal format</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p><table>  <tbody>    <tr>      <td>      <pre>   <font color="purple">printf</font>(<font color="red">"A=%x  B=%x\n"</font>, a, b);</pre>      </td>    </tr>  </tbody></table>The form <font face="Courier"><b>%x</b></font> formats an integer toprint in hexadecimal.</p><p><!----><a name="Formatting_Command_Summary"></a><font size="+2"><b>FormattingCommand Summary</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p><table>  <tbody>    <tr>      <td>      <dl>        <dd>          <table border="1">            <tbody>              <tr>                <td align="center"><font face="Times"><b>&nbsp;FormatCommand&nbsp;</b></font></td>                <td align="center"><font face="Times"><b>Data Type</b></font></td>                <td align="center"><b>Description</b></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; %d </font></td>                <td><font face="Courier" color="blue">&nbsp; int </font></td>                <td><font face="Times">&nbsp; decimal number </font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; %x </font></td>                <td><font face="Courier" color="blue">&nbsp; int </font></td>                <td><font face="Times">&nbsp; hexadecimal number </font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; %b </font></td>                <td><font face="Courier" color="blue">&nbsp; int </font></td>                <td><font face="Times">&nbsp; low byte as binary number                </font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; %l </font></td>                <td><font face="Courier" color="blue">&nbsp; long </font></td>                <td><font face="Times">&nbsp; long (decimal) integer </font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; %c </font></td>                <td><font face="Courier" color="blue">&nbsp; int </font></td>                <td><font face="Times">&nbsp; low byte as ASCIIcharacter &nbsp;</font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; %f </font></td>                <td><font face="Courier" color="blue">&nbsp; float </font></td>                <td><font face="Times">&nbsp; floating point number </font></td>              </tr>              <tr>                <td><font face="Courier">&nbsp; %s </font></td>                <td><font face="Courier"><font color="blue">&nbsp; char</font>                <font face="Times">array</font> &nbsp;</font></td>                <td><font face="Times">&nbsp; char array (string) </font></td>              </tr>            </tbody>          </table>        </dd>      </dl>      </td>    </tr>  </tbody></table><b>Special Note</b><table>  <tbody>    <tr>      <td><font face="Times"></font>      <ul>        <li><font face="Times">Depending on the display being used,the upper right position of the menu screens has a red system "heartbeat."This character continuously blinks between a large and small heart when theboard is operating properly. If the character stops blinking, the board hasfailed. The console screen supports display characters in 14 lines of 28characters.  Printing of long integers is supported on the console.  Inaddition characters can be placed in random positions on the screen (seedisplay clear(), display_set_xy(), and display_get_xy() functiondescriptions).          </font></li>      </ul>      </td>    </tr>  </tbody></table></p><p><!----><a name="Preprocessor"></a><font size="+3"><b>Preprocessor</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The preprocessor processes a file before it is sent to the compiler.The IC preprocessorallows definition of macros, and conditional compilation of sections ofcode. Usingpreprocessor macros for constants and function macros can make IC codemore efficientas well as easier to read. Using <font face="Courier" color="blue">#if</font>to conditionally compile code can be very useful, forinstance, for debugging purposes.</p><p>The special preprocessor command <font face="Courier" color="blue">#use</font>has been included to allow programs to cause aprogram to download to initiate the download of stored programs thatare not in the IClibrary. For example, suppose you have a set of stored programs in afile named"<font face="Courier">mylib.ic</font>", some of which you need for yourcurrent program to work.</p><pre>   <font color="darkgreen">/* <i>load my library</i> */</font>   <font color="blue">#use</font> <font color="red">"mylib.ic"</font>   <font color="blue">void</font> main()<br>   {<br>       <font color="blue">char</font> s[32] = <font color="red">"text string wrapping badly\n"</font>;<br>       fix (s);    <font color="darkgreen">/* <i>apply my fix function to s and print it</i> */</font>       <font color="purple">printf</font>(s);<br>   }<br></pre><!----><a name="Preprocessor_Macros"></a><font size="+2"><b>Preprocessor Macros</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>Preprocessor macros are defined by using the <font face="Courier" color="blue">#define</font> preprocessor directive at the startof a line. A macro is local to the file in which it is defined. Thefollowing example shows how to define preprocessor macros.</p><pre>  <font color="blue">#define</font> RIGHT_MOTOR 0<br>  <font color="blue">#define</font> LEFT_MOTOR  1<br>  <font color="blue">#define</font> GO_RIGHT(power) (<font color="purple">motor</font>(RIGHT_MOTOR,(power)))<br>  <font color="blue">#define</font> GO_LEFT(power)  (<font color="purple">motor</font>(LEFT_MOTOR,(power)))<br>  <font color="blue">#define</font> GO(left,right) {GO_LEFT(left); GO_RIGHT(right);}<br>  <font color="blue">void</font> main()<br>  {<br>      GO(0,0);<br>  }<br></pre>Preprocessor macro definitions start with the <font face="Courier" color="blue">#define</font> directive at the start of a line, andcontinue to the end of the line. After <font face="Courier" color="blue">#define</font> is the name of the macro, such as<b>RIGHT_MOTOR</b>. If there is a parenthesis directly after the nameof the macro, such as the<b>GO_RIGHT</b> macro has above, then the macro has arguments. The <b>GO_RIGHT</b>and<b>GO_LEFT</b> macros each take one argument. The GO macro takes twoarguments. After thename and the optional argument list is the body of the macro.<p>Each time a macro is invoked, it is replaced with its body. If themacro has arguments,then each place the argument appears in the body is replaced with theactual argumentprovided.</p><p>Invocations of macros without arguments look like global variablereferences.Invocations of macros with arguments look like calls to functions. Toan extent, this ishow they act. However, macro replacement happens before compilation,whereas globalreferences and function calls happen at run time. Also, function callsevaluate theirarguments before they are called, whereas macros simply perform textreplacement. Forexample, if the actual argument given to a macro contains a functioncall, and the macroinstantiates its argument more than once in its body, then the functionwould be calledmultiple times, whereas it would only be called once if it were beingpassed as a functionargument instead.</p><p>Appropriate use of macros can make IC programs and easier to read.It allows constantsto be given symbolic names without requiring storage and access time asa global would.It also allows macros with arguments to be used in cases when afunction call is desirablefor abstraction, without the performance penalty of calling a function.</p><p><!----><a name="Conditional_compilation"></a><font size="+2"><b>Conditionalcompilation</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>It is sometimes desirable to conditionally compile code. The primaryexample of this isthat you may want to perform debugging output sometimes, and disable itat other times.The IC preprocessor provides a convenient way of doing this by usingthe <font face="Courier" color="blue">#ifdef</font>directive.</p><pre>   <font color="blue">void</font> go_left(<font color="blue">int</font> power)<br>   {<br>       GO_LEFT(power);<br>   <font color="blue">#ifdef</font> DEBUG<br>       <font color="purple">printf</font>(<font color="red">"Going Left\n"</font>);<br>       <font color="purple">beep</font>();<br>   <font color="blue">#endif</font>   }</pre>In this example, when the macro <b>DEBUG</b> is defined, the debuggingmessage "Going Left"will be printed and the board will beep each time <b>go_left</b> iscalled. If the macro is notdefined, the message and beep will not happen. Each <font face="Courier" color="blue">#ifdef</font> must be follwed by an<font face="Courier" color="blue">#endif</font> at the end of the codewhich is being conditionally compiled. The macro to bechecked can be anything, and <font face="Courier" color="blue">#ifdef</font>blocks may be nested.<p>Unlike regular C preprocessors, macros cannot be conditionallydefined. If a macrodefinition occurs inside an <font face="Courier" color="blue">#ifdef</font>block, it will be defined regardless of whether the<font face="Courier" color="blue">#ifdef</font> evaluates to true orfalse. The compiler will generate a warning if macrodefinitions occur within an <font face="Courier" color="blue">#ifdef</font>block.</p><p>The <font face="Courier" color="blue">#if</font>, <font face="Courier" color="blue">#else</font>, and <font face="Courier" color="blue">#elif</font> directives are also available, but areoutside the scope ofthis document. Refer to a C reference manual for how to use them.</p><p><!----><a name="Comparison_with_regular_C_preprocessors"></a><font size="+2"><b>Comparisonwith regular C preprocessors</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>The way in which IC deals with loading multiple files isfundamentally different from theway in which it is done in standard C. In particular, when usingstandard C, files arecompiled completely independently of each other, then linked together.In IC, on theother hand, all files are compiled together. This is why standard Cneeds functionprototypes and <b>extern</b> global definitions in order for multiplefiles to share functionsand globals, while IC does not.</p><p>In a standard C preprocessor, preprocessor macros defined in one Cfile cannot be used inanother C file unless defined again. Also, the scope of macros is onlyfrom the point ofdefinition to the end of the file. The solution then is to have theprototypes, <b>extern</b>declarations, and macros in header files which are then included at thetop of each C fileusing the <font face="Courier">#include</font> directive. This styleinteracts well with the fact that each file iscompiled independent of all the others.</p><p>However, since declarations in IC do not file scope, it would beinconsistent to have apreprocessor with file scope. Therefore, for consistency it wasdesirable to give ICmacros the same behavior as globals and functions. Therefore,preprocessor macros haveglobal scope. If a macro is defined anywhere in the files loaded intoIC, it is definedeverywhere. Therefore, the <font face="Courier">#include</font> and<font face="Courier">#undef</font> directives did not seem to have anyappropriate purpose, and were accordingly left out.</p><p>The fact that <font face="Courier" color="blue">#define</font>directives contained within<font face="Courier" color="blue">#if</font> blocks are definedregardless ofwhether the <font face="Courier" color="blue">#if</font> evaluates tobe true or false is a side effectof making the preprocessor macros have global scope.</p><p>Other than these modifications, the IC preprocessor should becompatible with regular Cpreprocessors.</p><p><!----><a name="The_IC_Library_File"></a><font size="+3"><b>The IC Library File</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p>Library files provide standard C functions for interfacing withhardware on the robotcontroller board. These functions are written either in C or asassembly language drivers.Library files provide functions to do things like control motors, maketones, and inputsensors values.</p><p>IC automatically loads the library file every time it is invoked.Depending on whichboard is being used, a different library file will be required. IC maybe configured to loaddifferent library files as its default; IC will automatically load thecorrect library for theboard you're using at the moment.</p><p>Separate documentation covers all library functions available forthe Handy Board, the Lego RCX, andthe XBC; if you have another board, see your owner's manual fordocumentation.</p><p>To understand better how the library functions work, study of thelibrary file source codeis recommended; e.g., the main library file for the Handy Board isnamed <font face="Courier">lib_hb.ic</font>.</p><p>For convenience, a description of some of the more commonly usedlibrary functions follows.</p><p><!----><a name="Commonly_Used_IC_Library_Functions"></a><font size="+2"><b>CommonlyUsed IC Library Functions</b></font> &nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font></p><p></p><pre><a name="digitalx"></a><font color="darkblue">digital</font>(&lt;<font face="Times"><i>port#</i></font>);<br>  <font color="darkgreen">/* <i>returns 0 if the switch attached to the port is open and<br>     returns 1 if the switch is closed.  Digital ports are numbered<br>     7-15.  Typically used for bumpers or limit switches.</i> */</font><a name="analogx"></a><font color="darkblue">analog</font>(&lt;<font face="Times"><i>port#</i></font>);<br>  <font color="darkgreen">/* <i>returns the analog value of the port (a value in the range 0-255).<br>     Analog ports on the handy board are numbered 2-6 and 16-23.  Light<br>     sensors and range sensors are examples of sensors you would<br>     use in analog ports (only on Handy Board).</i> */</font><font color="darkblue">sleep</font>(&lt;<font face="Times"><i>float_secs</i></font>&gt;);<br>  <font color="darkgreen">/* <i>waits specified number of seconds</i> */</font><a name="tonex"></a><font color="darkblue">beep</font>();<br>  <font color="darkgreen">/* <i>causes a beep sound</i> */</font><a name="lightx"></a><font color="darkblue">tone</font>(&lt;<font face="Times"><i>float_frequency</i></font>&gt;, &lt;<font face="Times"><i>float_secs</i></font>&gt;)<br>  <font color="darkgreen">/* <i>plays at specified frequency for specified time (seconds)</i> */</font><a name="printfx"></a><font color="darkblue">printf</font>(&lt;<font face="Times"><i>string</i></font>&gt;, &lt;<font face="Times"><i>arg1</i></font>&gt;, &lt;<font face="Times"><i>arg2</i></font>&gt;, ... );<br>  <font color="darkgreen">/* <i>prints &lt;<i>string</i>&gt;.  If the string contains % codes then the &lt;<i>args</i>&gt;<br>     after the string will be printed in place of the % codes in the<br>     format specified by the code. %d prints a decimal number. %f<br>     prints a floating point number. %c prints a character, %b prints<br>     an integer in binary, %x prints an integer in hexadecimal.</i> */</font><a name="motorx"></a><font color="darkblue">motor</font>(&lt;<i>motor_#</i>&gt;, &lt;<i>speed</i>&gt;)<br>  <font color="darkgreen">/* <i>controls the motors. &lt;<i>motor_#</i>&gt; is an integer between 0 and 3 (1<br>     less for RCX).  &lt;<i>speed</i>&gt; is an integer between -100 and 100 where 0<br>     means the motor is off and negative numbers run the motor in the<br>     reverse direction</i> */</font><a name="fdx"></a><font color="darkblue">fd</font>(&lt;<i>motor_#</i>&gt;);<br>  <font color="darkgreen">/* <i>turns on the motor specified (direction is determined by plug<br>     orientation</i> */</font><a name="bkx"></a><font color="darkblue">bk</font>(&lt;<i>motor_#</i>&gt;);<br>  <font color="darkgreen">/* <i>turns on the motor specified in the opposite direction from fd</i> */</font><a name="offx"></a><font color="darkblue">off</font>(&lt;<i>motor_#</i>&gt;);<br>  <font color="darkgreen">/* <i>turns off the motor specified</i> */</font><a name="aox"></a><font color="darkblue">ao</font>();<br>  <font color="darkgreen">/* <i>turns all motor ports off</i> */</font></port></port></pre><!----><a name="Processes"></a><font size="+2"><b>Processes</b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>Processes work in parallel. Each process, once it is started, willcontinue until it finishesor until it is killed by another process using the<nobr><font face="Courier"><font color="purple">kill_process</font>(&lt;</font><i>process_id</i><font face="Courier">)&gt;);</font></nobr>statement. Each process that is active gets 50ms of processing time.Then the process ispaused temporarily and the next process gets its share of time. Thiscontinues until allthe active process have gotten a slice of time, then it all repeatsagain. From the user'sstandpoint it appears that all the active processes are running inparallel.</p><p>Processes can communicate with one another by reading and modifyingglobal variables.The globals can be used as semaphores so that one process can signalanother. ProcessIDs may also be stored in globals so that one process can kill anotherwhen needed.</p><p>Up to 4 processes initiated by the <nobr><font face="Courier"><font color="purple">start_process</font>()</font></nobr> library functioncan be active atany time.</p><p>The library functions for controlling processes are:</p><pre><a name="start_processx"></a><font color="darkblue">start_process</font>(&lt;<font face="Times"><i>function_name</i></font>&gt;(&lt;<font face="Times"><i>arg1</i></font>&gt;, &lt;<font face="Times"><i>arg2</i></font>&gt;, . . .));<br>  <font color="darkgreen">/* <i>start_process returns an integer that is the &lt;process_id&gt;<br>     and starts the function &lt;function_name&gt; as a separate<br>     process</i> */</font><a name="deferx"></a><font color="darkblue">defer</font>();<br>  <font color="darkgreen">/* <i>when placed in a function that is used as a process this<br>     will cause that process to give up the remainder of its time<br>     slice whenever defer is called</i> */</font><a name="kill_processx"></a><font color="darkblue">kill_process</font>(&lt;<font face="Times"><i>process_id</i></font>&gt;);<br>  <font color="darkgreen">/* <i>this will terminate the process specified by the<br>     &lt;process_id&gt;</i> */</font></pre><!----><a name="Encoders"></a> <font size="+2"><b>Encoders </b></font>&nbsp;&nbsp;<font size="1"><a href="#PM_Index">Index</a></font><p>The <font face="Courier"><font color="purple">enable_encoder</font>()</font>library function is used to start a process which updates thetransition count for the encoder specified. The encoder libraryfunctions are designed for sensors connected to (digital) ports8-15.  Every enabled encoder uses a lot of the processor -- so don'tenable an encoder unless you are going to use it, and <font color="red"><i>neverput an enable statement inside of a loop</i></font>.</p><pre><a name="xenable_encoder"></a><font color="darkblue">enable_encoder</font>(&lt;<font face="Times"><i>port#</i></font>&gt;);<br>  <font color="darkgreen">/* <i>turns on the specified encoder (which are plugged into digital<br>     ports 8-15). This should be done only once - never enable an<br>     already enabled encoder.  If an encoder is not enabled<br>     read_encoder will always return 0.</i> */</font><a name="xdisable_encoder"></a><font color="darkblue">disable_encoder</font>(&lt;<font face="Times"><i>port#</i></font>&gt;)<br>  <font color="darkgreen">/* <i>turns off the specified encoder</i> */</font><a name="xreset_encoder"></a><font color="darkblue">reset_encoder</font>(&lt;<font face="Times"><i>port#</i></font>&gt;)<br>  <font color="darkgreen">/* <i>sets the specified encoder value to 0</i> */</font><a name="xread_encoder"></a><font color="darkblue">read_encoder</font>(&lt;<font face="Times"><i>port#</i></font>&gt;)<br>  <font color="darkgreen">/* <i>returns an int that is the current value of the specified<br>     encoder</i> */</font></pre><p></p><hr><!----><a name="sensors"></a><br><br><font size="6"></font><p align="center"><font size="6"><b>Sensors</b><br><font size="2"></font></font></p><table border="1" cellpadding="5" cellspacing="0">  <tbody>    <tr>      <td align="center" valign="center"><font face="Times"> <a href="#light_sensor"> <br>      <img border="0" src="image002.gif"><br>      <br>      <br>      <b>Light Sensor</b><br>      </a> (analog)</font> </td>      <td align="center" valign="center"><font face="Times"> <a href="#top_hat_sensor"> <img border="0" src="image003.gif"><br>      <b>Infrared "Top Hat" Reflectance Sensor</b><br>      </a> (analog)</font> </td>      <td align="center" valign="center"><font face="Times"> <a href="#et_sensor"> <img border="0" src="image004.gif"><br>      <b> Infrared "E.T." Distance Sensor</b><br>      </a> (high-impedance analog)</font> </td>    </tr>    <tr>      <td align="center" valign="center" colspan="2"><font face="Times">      <a href="#touch_sensors"> <img border="0" src="image005.gif"><br>      <b>Touch Sensors</b><br>      </a> (digital)</font> </td>      <td align="center" valign="center"><font face="Times"> <a href="#break_beam_sensor"> <img border="0" src="image006.gif"><br>      <b> Infrared "Break Beam" Sensor</b><br>      </a> (digital)</font> </td>    </tr>    <tr>      <td align="center" valign="center"><font face="Times"> <a href="#sonar_sensor"> <img border="0" src="image007.gif"><br>      <b>Sonar<br>(Ultrasonic Rangefinder)</b> </a> </font></td>      <td>&nbsp;</td>    </tr>  </tbody></table><font size="6"><font size="2"><br><br><br><br></font></font><p><!------------------------------><font size="6"><font size="2"><font size="5"><b>Light Sensor </b>(analog)<a name="light_sensor"></a><font size="3"><br><br><img border="0" src="image002.gif"><br></font></font></font></font></p><ul>  <font size="6"><font size="2"><font size="5"><font size="3"> <li>Analogsensor</li>  <li>Connect to ports 2-6</li>  <li>Access with function <font face="Courier"><font color="purple"><a href="#analog">analog</a></font>(&lt;<i>port#</i>&gt;)</font> </li>  <li>Low values indicate bright light</li>  <li>High values indicate low light</li>  <li>Sensor is somewhat directional and can be made more so usingblack paper or tape or an opaque straw or lego to shade extraneouslight.&nbsp; Sensor can be attenuated by placing paper in front.</li>  </font></font></font></font></ul><font size="6"><font size="2"><font size="5"><font size="3"><br><br><br><br></font></font></font></font><p><!------------------------------><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><!--a name="top_hat_sensor"></a--><b>Infrared "Top Hat" Reflectance</b> <b>Sensor</b> (analog)<a name="top_hat_sensor"></a><font size="3"><br><br><img border="0" src="image003.gif"><br></font></font></font></font></font></font></p><ul>  <font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"> <li>Analog sensor</li>  <li>Connect to ports 2-6</li>  <li>Access with function <font face="Courier"><font color="purple"><a href="#analog">analog</a></font>(&lt;<i>port#</i>&gt;)</font> </li>  <li>Low values indicate bright light, light color, or close proximity</li>  <li>High values indicate low light, dark color, or distance ofseveral inches</li>  <li>Sensor has a reflectance range of about 3 inches</li>  </font></font></font></font></font></font></ul><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><br><br><br><br></font></font></font></font></font></font><p><!------------------------------><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><a name="et_sensor"></a><b>Infrared "E.T." Distance Sensor </b>(high-impedance analog)<font size="3"><br><br><img border="0" src="image004.gif"><br></font></font></font></font></font></font></font></font></p><ul>  <font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"> <li>Floatinganalog sensor</li>  <li>Connect to port 0 or 1</li>  <li>Access with function <font face="Courier"><font color="purple"><a href="#analog">analog</a></font>(&lt;<i>port#</i>&gt;)</font> </li>  <li>Low values indicate large distance</li>  <li>High values indicate distance approaching ~4 inches</li>  <li>Range is 4-30 inches.&nbsp; Result is approximately 1/(d)^2. Objectscloser than 4 inches will appear to be far away.</li>  <li>Sharp Electronics part number GP2D12</li>  <li>Sensor shines a narrow infrared beam, and measures the angle ofthe beam return using a&nbsp; position-sensitive detector (PSD):</li>  <img border="0" src="image009.gif"></font></font></font></font></font></font></font></font></ul><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><br><br><br><br></font></font></font></font></font></font></font></font><p><!------------------------------><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><a name="touch_sensors"></a><b>Touch Sensors </b>(digital)<font size="3"><br><br><img border="0" src="image005.gif"><br></font></font></font></font></font></font></font></font></font></font></p><ul>  <font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"> <li>Digital sensors</li>  <li>Connect to ports 8-15</li>  <li>Access with function <font face="Courier"><font color="purple"><a href="#digital">digital</a></font>(&lt;<i>port#</i>&gt;)</font> </li>  <li>1 indicates switch is closed</li>  <li>0 indicates switch is open</li>  <li>These make good bumpers and can be used for limit switches on anactuator</li>  </font></font></font></font></font></font></font></font></font></font></ul><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><br><br><br><br></font></font></font></font></font></font></font></font></font></font><p><!------------------------------><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><a name="break_beam_sensor"></a><b>Infrared "Break Beam" Sensor </b>(digital)<font size="3"><br><br><img border="0" src="image010.gif"><br></font></font></font></font></font></font></font></font></font></font></font></font></p><ul>  <font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"> <li>Digital sensor</li>  <li>Connect to ports 8-15</li>  <li>Access with function <font face="Courier"><font color="purple"><a href="#digital">digital</a></font>(&lt;<i>port#</i>&gt;)</font> </li>  <li>1 indicates slot is empty</li>  <li>0 indicates slot is blocked</li>  <li>These can be used much like touch sensors (if the object beingtouched fits in the slot)</li>  <li>Special abilities when used as encoders -   This can be useful for the slot sensor in conjunctionwith a wheel, which allows measuring rotational rate and total angle.</li>  </font></font></font></font></font></font></font></font></font></font></font></font></ul><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><br><br><br></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font><p><!------------------------------><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><a name="sonar_sensor"></a><b>Sonar (Ultrasonic Rangefinder)</b><font size="3"><br><br><img border="0" src="image011.gif"><br></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></p><ul>  <font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"> <li>Timedanalog sensor.&nbsp; Sends a "ping" of high-pitched sound and listensfor an echo</li>  <li>Connect to ports 8-15</li>  <li>Access with function <font face="Courier"><font color="purple"><a href="#sonar">sonar</a></font>()</font> </li>  <li>Returned value is distance in mm to closest object in field ofview</li>  <li>Range is approximately 30-2000mm</li>  <li>If object is too close or too far, the sensor will not detect areturn</li>  <li>No return (because objects are too close or too far) gives valueof 32767</li>  <li>Wait at least .03 seconds between calls to <font face="Courier"><font color="purple"><a href="#sonar">sonar</a></font>()</font> to allowechos to die out (you could call <font face="Courier"><font color="purple"><a href="#sleep">sleep</a></font>(.03))</font> </li>  <li>Sound frequency is 40 kilohertz (40,000 cycles per second).&nbsp;This is an ultrasonic frequency because most humans can only hear up 20kilohertz.</li>  <li>Speed of sound is ~300mm/ms</li>  <li>sonar() times the echo, divides by two and multiplies by speed ofsound</li>  <li>Devantech part number SRF04</li>  <li>The sonar field of view is a 30 degree teardrop:</li>  <br>  <br>  <img border="0" src="image012.gif"></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font>  <p></p></ul><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><br><br><br><br></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font><p><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><a name="Functions"></a><font size="+4"><b>XBC Library Function Descriptions</b></font><br></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></p><p><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3">(alphabeticorder) <br><table cellspacing="5">  <tbody>    <tr>      <td valign="top"><a name="a_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">a_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">a_button</font>()</font><br>Reads the value (0 or 1) of the A button (button #1).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="alloff"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">alloff</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">alloff</font>()</font><br>Turns off all motors. <font face="Courier" color="purple">ao</font> isa short form for <font face="Courier" color="purple">alloff</font>.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="analog"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">analog</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">analog</font>(<font color="blue">int</font> p)</font><br>Returns the value of the sensor installed at the port numbered p. Theresult is an integer between 0 and 255. The function can be used withanalog ports 0 through 6 (see note below on port 7). Ports 0 and 1 arefloating (used for sensors such as an optical range finder). If the <font face="Courier"><font color="purple">analog</font>()</font> function isapplied to a port that is implemented digitally in hardware, then thevalue 255 is returned if the hardware digital reading is 1 (as if adigital switch is open, and the pull up resistors are causing a highreading), and the value 0 is returned if the hardware digital readingis 0 (as if a digital switch is closed and pulling the reading nearground). Ports are numbered as marked. Since ports 0 and 1 arefloating, the value cannot be predicted without a sensor inserted. <font color="red">NOTE: Port 7 is used internally to monitor batteryvoltage and so is not available for other uses.</font></font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="analog12"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">analog12</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">analog12</font>(<font color="blue">int</font> p)</font><br>12-bit version of the <font face="Courier" color="purple">analog</font>function. The returned value is in the range 0 to 4095 rather than 0 to255.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="any_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">any_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">any_button</font>()</font><br>Returns 1 if any button (other than START or SELECT) is pressed.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="ao"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">ao</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">ao</font>()</font><br>Turns off all motors.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="atan"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">atan</font>&nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">atan</font>(<font color="blue">float</font> angle)</font><br>Returns the arc tangent of the angle. Angle is specified in radians;the result is in radians.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="b_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">b_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">b_button</font>()</font><br>Reads the value (0 or 1) of the B button (button #2).</font></font></dd>      </dl>      </td>    </tr><!--<tr><td valign=top><a name="backward"></a>	    </td>    <td><font face="Times"><font face="Courier" color=purple>backward</font> &nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>		<dl><dd><font face="Times">Format: <font face="Courier"> <font color=blue>void</font> <font color=purple>backward</font>()</font><br>		Runs all motor ports in the backward direction.</font></td></tr>-->    <tr>      <td valign="top"><a name="beep"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">beep</font>&nbsp;&nbsp;&nbsp;[Category: Sound] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">beep</font>()</font><br>Produces a tone of 500 Hertz for a period of 0.3 seconds. Returns whenthe tone is finished.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="beeper_off"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">beeper_off</font>&nbsp;&nbsp;&nbsp;[Category: Sound] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">beeper_off</font>()</font><br>Turns off the beeper.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="beeper_on"></a></td>      <td><font face="Times"><font face="Courier" color="purple">beeper_on</font>&nbsp;&nbsp;&nbsp;[Category: Sound] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">beeper_on</font>()</font><br>Turns on the beeper at last frequency selected by the former function.The beeper remains on until the <font face="Courier" color="purple">beeper_off</font>function is executed.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="bk"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">bk</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">bk</font>(<font color="blue">int</font> m)</font><br>Turns motor <font face="Courier">m</font> on full speed in thebackward direction.<br>Example: <br>          <font face="Courier">&nbsp;&nbsp;&nbsp;<font color="purple">bk</font>(1);</font></font></font></dd>      </dl>      </td>    </tr>    <tr>      <td style="vertical-align: top;"><br>      </td>      <td style="vertical-align: top;"><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Times"><font face="Courier" color="purple">block_motor_done</font>&nbsp; [Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">block_motor_done</font>(<font color="blue">int</font> m)</font><br>Function does not return until specified motor completes any executingspeed or position control moves.<br>Example: <br>          <font face="Courier">&nbsp;&nbsp; <font color="purple">mrp<span style="color: rgb(0, 0, 0);">(0,500,20000L);</span><br>&nbsp;&nbsp; block_motor_done</font>(1);</font></font></font></dd>      </dl>      </font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></td>    </tr>    <tr>      <td style="vertical-align: top;"><br>      </td>      <td style="vertical-align: top;"><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Times"><font face="Courier" color="purple">bmd</font> &nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">bmd</font>(<font color="blue">int</font> m)</font><br>Function does not return until specified motor completes any executingspeed or position control moves.<br>Example: <br>          <font face="Courier">&nbsp;&nbsp; <font color="purple">mrp<span style="color: rgb(0, 0, 0);">(0,500,20000L);</span><br>&nbsp;&nbsp; bmd</font>(1);</font></font></font></dd>      </dl>      </font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></td>    </tr>    <tr>      <td valign="top"><a name="button_held"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">button_held</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"><font color="blue">int</font> <font color="purple">button_held</font>(<font color="blue">int</font> button_nbr, <font color="blue">int</font>state1, <font color="blue">int</font> state2)</font><br>          <font face="Courier">state1</font> and <font face="Courier">state2</font>are bit vectors obtained by using <font face="Courier" color="purple">button_state</font>.The returned value is 1 if the addressed button was pressed at bothstate1 and state2.          </font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="button_hit"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">button_hit</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"><font color="blue">int</font> <font color="purple">button_hit</font>(<font color="blue">int</font> button_nbr, <font color="blue">int</font>state1, <font color="blue">int</font> state2)</font><br>          <font face="Courier">state1</font> and <font face="Courier">state2</font>are bit vectors obtained by using <font face="Courier" color="purple">button_state</font>.The returned value is 1 if the addressed button was not pressed atstate1 but is pressed at state2.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="button_released"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">button_released</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"><font color="blue">int</font> <font color="purple">button_hit</font>(<font color="blue">int</font> button_nbr, <font color="blue">int</font>state1, <font color="blue">int</font> state2)</font><br>          <font face="Courier">state1</font> and <font face="Courier">state2</font>are bit vectors obtained by using <font face="Courier" color="purple">button_state</font>.The returned value is 1 if the addressed button was pressed at state 1,but is not pressed at state2.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="button_state"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">button_state</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">button_state</font>()</font><br>Returns a bit vector of the state of all the buttons. The <font face="Courier" color="purple">check_button</font> function uses thisto return the value of a button (0 or 1)</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="button_transit"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">button_transit</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"><font color="blue">int</font> <font color="purple">button_transit</font>(<font color="blue">int</font> button_nbr, <font color="blue">int</font>state1, <font color="blue">int</font> state2)</font><br>          <font face="Courier">state1</font> and <font face="Courier">state2</font>are bit vectors obtained by using <font face="Courier" color="purple">button_state</font>.The returned value is 1 if the addressed button was pressed or releasedin going from state1 to state2.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="check_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">check_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">check_button</font>(<font color="blue">int</font> button_nbr)</font><br>Reads the value (0 or 1) of the button specified. A=1, B=2, R=256,L=512, right=16, left=32, up=64, down=128.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="choose_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">choose_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format:<font face="Courier"> <font color="blue">int</font> <font color="purple">choose_button</font>()</font><br>Returns value of button labeled A.<br>Example:<br>          <font face="Courier">&nbsp;&nbsp;&nbsp;<font color="darkgreen">/*wait for button to be pressed; then wait for it to be<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;released so that button press isdebounced */</font><br>&nbsp;&nbsp;&nbsp;<font color="blue">while</font> (!<font color="purple">choose_button</font>()){}<br>&nbsp;&nbsp;&nbsp;<font color="blue">while</font> (<font color="purple">choose_button</font>()){}</font></font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="clear_motor_position_counter"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">clear_motor_position_counter</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">clear_motor_position_counter</font>(<font color="blue">int</font> motor_nbr)</font><br>Reset the position counter for the motor specified to 0.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="cos"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">cos</font>&nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">cos</font>(<font color="blue">float</font> angle)</font><br>Returns cosine of angle. Angle is specified in radians; result is inradians.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="defer"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">defer</font>&nbsp;&nbsp;&nbsp;[Category: Processes] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">defer</font>()</font><br>Makes a process swap out immediately after the function is called.Useful if a process knows that it will not need to do any work untilthe next time around the scheduler loop. <font face="Courier"><font color="purple">defer</font>()</font> is implemented as a C built-infunction.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="digital"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">digital</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">digital</font>(<font color="blue">int</font> p)</font><br>Returns the value of the sensor in sensor port p, as a true/false value(1 for true and 0 for false). Sensors are expected to be active low,meaning that they are valued at zero volts in the active, or true,state. Thus the library function returns the inverse of the actualreading from the digital hardware: if the reading is zero volts orlogic zero, the <font face="Courier"><font color="purple">digital</font>()</font>function will return true. Valid for digital ports 8-15.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="disable_encoder"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">disable_encoder</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">disable_encoder</font>(<font color="blue">int</font> p)</font><br>Disables the given encoder and prevents it from counting. Each encoderuses processing time every time it receives a pulse while enabled, sothey should be disabled when you no longer need the encoder's data.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="disable_extra_encoder"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">disable_extra_encoder</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">disable_extra_encoder</font>(<font color="blue">int</font> p)</font><br>Disables encoder processing for the addressed extra port (16-23).Requires use of a dongle to access port).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="disable_servos"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">disable_servos</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">disable_servos</font>()</font><br>Disables the servo motor ports (powers down all servo motors).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="display_clear"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">display_clear</font>&nbsp;&nbsp;&nbsp;[Category: Output] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">display_clear</font>()</font><br>Clears the display screen to blank.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="display_get_xy"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">display_get_xy</font>&nbsp;&nbsp;&nbsp;[Category: Output] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">display_get_xy</font>(*<font color="blue">int</font> x, *<font color="blue">int</font>)</font><br>Assigns to <font face="Courier">x</font> and <font face="Courier">y</font>the current (column,row) coordinates on the display screen for the next          <font face="Courier" color="purple">printf</font>.o&lt;=column&lt;=27 and 0&lt;=row&lt;=13</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="display_set_xy"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">display_set_xy</font>&nbsp;&nbsp;&nbsp;[Category: Output] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">display_set_xy</font>(<font color="blue">int</font> x, <font color="blue">int</font>)</font><br>Positions the position on the display screen for the next <font face="Courier" color="purple">printf</font> at the (column,row)coordinates given by <font face="Courier">x</font> and <font face="Courier">y</font>.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="down_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">down_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">down_button</font>()</font><br>Reads the value (0 or 1) of the move down button (button #128).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="enable_encoder"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">enable_encoder</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">enable_encoder</font>(<font color="blue">int</font> p)</font><br>Enables the given encoder to start counting pulses and resets itscounter to zero. By default encoders start in the disabled state andmust be enabled before they start counting.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="enable_extra_encoder"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">enable_extra_encoder</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">enable_extra_encoder</font>(<font color="blue">int</font> p)</font><br>Enables encoder processing for the addressed extra port (16-23).Requires use of a dongle to access port).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="enable_servos"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">enable_servos</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">enable_servos</font>()</font><br>Enables all servo motor ports.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="escape_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">escape_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format:<font face="Courier"> <font color="blue">int</font> <font color="purple">escape_button</font>()</font><br>Returns value of button labeled B: 1 if pressed and 0 if released.Example:<br>          <font face="Courier">&nbsp;&nbsp;&nbsp;<font color="darkgreen">/*wait until escape button pressed */</font><br>&nbsp;&nbsp;&nbsp;<font color="blue">while</font> (!<font color="purple">escape_button</font>()){}</font></font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="exp10"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">exp10</font>&nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">exp10</font>(<font color="blue">float</font> num)</font><br>Returns 10 to the num power.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="exp"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">exp</font>&nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">exp</font>(<font color="blue">float</font> num)</font><br>Returns e to the num power.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="extra_digital"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">extra_digital</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">extra_digital</font>(<font color="blue">int</font> p)</font><br>Same as digital except applies to ports 16-23. A "dongle" is usuallyused to access these ports.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="fd"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">fd</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">fd</font>(<font color="blue">int</font> m)</font><br>Turns motor m on full in the forward direction.<br>Example:<br>          <font face="Courier">&nbsp;&nbsp;&nbsp;<font color="purple">fd</font>(3);</font></font></font></dd>      </dl>      </td>    </tr><!--<tr><td valign=top><a name="forward"></a>		</td>    <td><font face="Times"><font face="Courier" color=purple>forward</font> &nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>		<dl><dd><font face="Times">Format: <font face="Courier"> <font color=blue>void</font> <font color=purple>forward</font>()</font><br>		Runs all motor ports in the foward direction.</font></td></tr>-->    <tr>      <td valign="top"><a name="freeze"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">freeze</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">freeze</font>(<font color="blue">int</font> m)</font><br>Freezes motor m (prevents continued motor rotation, in contrast to <font face="Courier" color="purple">off</font>, which allows the motor to"coast").<br>          </font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="get_motion_acceleration"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">get_motion_acceleration</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">get_motion_acceleration</font>(<font color="blue">int</font> m)</font><br>It is recommended that the default motion acceleration set by firmwareon bootup be used. The function returns the current value used formotor acceleration for motor <font face="Courier">m</font>.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="get_motor_done"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">get_motor_done</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">get_motor_done</font>(<font color="blue">int</font> m)</font><br>Returns whether the motor has finished a move with specified position.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="get_motor_position_counter"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">get_motor_position_counter</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"><font color="blue">long</font> <font color="purple">get_motor_position_counter</font>(<font color="blue">int</font> m)</font><br>Returns the current motor position value for motor <font face="Courier">m</font>(a value which is continually being updated for each motor using backEMF; a typical discrimination for a given motor is on the order of 1100position "ticks" per rotation)</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="get_scaled_sonar_value"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">get_scaled_sonar_value</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"><font color="blue">int</font> <font color="purple">get_scaled_sonar_value</font>(<font color="blue">int</font> port)</font><br>Returns the current value of the addressed sonar, scaled accorrding tothe <font face="Courier" color="purple">scale_sonar</font> function.Routine for non-blocking sonar (<font face="Courier" color="purple">sonar</font>function blocks).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="get_servo_position"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">get_servo_position</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">get_servo_position</font>(<font color="blue">int</font> srv)</font><br>Returns the position value of the servo in port <font face="Courier">srv</font>.The value is in the range 0 to 255. There are 4 servo ports (0, 1, 2,3).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="get_sonar_ping_time"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">get_sonar_ping_time</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"><font color="blue">int</font> <font color="purple">get_sonar_ping_time</font>(<font color="blue">int</font> port)</font><br>Routine for non-blocking sonar (<font face="Courier" color="purple">sonar</font>function blocks).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="hog_processor"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">hog_processor</font>&nbsp;&nbsp;&nbsp;[Category: Processes] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">hog_processor</font>()</font><br>Allocates an additional 256 milliseconds of execution to the currentlyrunning process. If this function is called repeatedly, the system willwedge and only execute the process that is calling <font face="Courier"><font color="purple">hog_processor</font>()</font>. Only a system reset willunwedge from this state. Needless to say, this function should be usedwith extreme care, and should not be placed in a loop, unless wedgingthe machine is the desired outcome.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="kill_process"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">kill_process</font>&nbsp;&nbsp;&nbsp;[Category: Processes] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">kill_process</font>(<font color="blue">int</font> pid);</font><br>The <font face="Courier" color="purple">kill_process</font> functionis used to destroy processes. Processes are destroyed by passing theirprocess ID number to <font face="Courier" color="purple">kill_process</font>.If the return value is 0, then the process was destroyed. If the returnvalue is 1, then the process was not found. The following code showsthe main process creating a <font face="Courier">check_sensor</font>process, and then destroying it one second later:          <pre>    <font color="blue">void</font> main() {<br>        <font color="blue">int</font> pid;<br>        pid=<font color="purple">start_process</font>(check_sensor(2));<br>        <font color="purple">sleep</font>(1.0);<br>        <font color="purple">kill_process</font>(pid);<br>    }</pre>          </font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="l_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">l_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">l_button</font>()</font><br>Reads the value (0 or 1) of the L (shoulder) button (button #512).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="left_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">left_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">left_button</font>()</font><br>Reads the value (0 or 1) of the move left button (button #32).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="log10"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">log10</font>&nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">log10</font>(<font color="blue">float</font> num)</font><br>Returns the logarithm of <font face="Courier">num</font> to the base10.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="log"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">log</font>&nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">log</font>(<font color="blue">float</font> num)</font><br>Returns the natural logarithm of <font face="Courier">num</font>.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td style="vertical-align: top;"><br>      </td>      <td style="vertical-align: top;"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Times"><font face="Courier" color="purple">mav</font>&nbsp;&nbsp; [Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">mav</font>(<font color="blue">int</font> m, <font color="blue">int</font> vel)</font><br>This function is the same as move_at_velocity </font></font></dd>      </dl>      </font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></td>    </tr>    <tr>      <td valign="top"><a name="motor"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">motor</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">motor</font>(<font color="blue">int</font> m, <font color="blue">int</font> p)</font><br>Turns on motor <font face="Courier">m</font> at scaled PWM duty cyclepercentage&nbsp; <font face="Courier">p</font>. Power levels rangefrom 100 for full on forward to -100 for full on backward. <br>          </font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="move_at_velocity"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">move_at_velocity</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">move_at_velocity</font>(<font color="blue">int</font> m, <font color="blue">int</font> vel)</font><br>Moves motor <font face="Courier">m</font> at velocity <font face="Courier">vel</font> indefinitely. The velocity range is -1000 to1000 ticks per second. <br>          </font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="move_relative_position"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">move_relative_position</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">move_relative_position</font>(<font color="blue">int</font> m, <font color="blue">int</font> speed, <font color="blue">long</font> pos)</font><br>Moves motor <font face="Courier">m</font> at velocity <font face="Courier">vel</font> from its current position <font face="Courier">curr_pos</font> to <font face="Courier">curr_pos + pos</font>.The speed range is 0 to 1000 ticks per second. Example: <br>          <font face="Courier">&nbsp;&nbsp;&nbsp;<font color="purple">move_relative_position</font>(1,275,-1100L);</font></font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="move_to_position"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">move_to_position</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">move_to_position</font>(<font color="blue">int</font> m, <font color="blue">int</font> speed, <font color="blue">long</font> pos)</font><br>Moves motor <font face="Courier">m</font> at velocity <font face="Courier">vel</font> from its current position <font face="Courier">curr_pos</font> to <font face="Courier">pos</font>.The speed range is 0 to 1000. Note that if the motor is already at <font face="Courier">pos</font>, the motor doesn't move.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="mrp"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">mrp</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">mrp</font>(<font color="blue">int</font> m, <font color="blue">int</font> vel, <font color="blue">long</font> pos)</font><br>This function is the same as move_relative_position.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td style="vertical-align: top;"><br>      </td>      <td style="vertical-align: top;"><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Times"><font face="Courier" color="purple">mtp</font>&nbsp; [Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">mtp</font>(<font color="blue">int</font> m, <font color="blue">int</font> vel, <font color="blue">long</font> pos)</font><br>This function is the same as move_to_position.</font></font></dd>      </dl>      </font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></td>    </tr>    <tr>      <td valign="top"><a name="mseconds"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">mseconds</font>&nbsp;&nbsp;&nbsp;[Category: Time] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">long</font> <font color="purple">mseconds</font>()</font><br>Returns the count of system time in milliseconds. Time count is resetby hardware reset (i.e., pressing reset switch on board) or thefunction <font face="Courier"><font color="purple">reset_system_time</font>()</font>.          <br>          <font face="Courier"><font color="purple">mseconds</font>()</font>is implemented as a C primitive (not as a library function).          </font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="msleep"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">msleep</font>&nbsp;&nbsp;&nbsp;[Category: Time] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">msleep</font>(<font color="blue">long</font> msec)</font><br>Waits for an amount of time equal to or greater than <font face="Courier">msec</font> milliseconds. <font face="Courier">msec</font>is a <font face="Courier" color="blue">long</font> integer.<br>Example:<br>          <font face="Courier">&nbsp;&nbsp;&nbsp;<font color="darkgreen">/*wait for 1.5 seconds */</font><font color="purple"> msleep</font>(1500L);</font></font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="off"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">off</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">off</font>(<font color="blue">int</font> m)</font><br>Turns off motor <font face="Courier">m</font>. <br>Example: <br>          <font face="Courier">&nbsp;&nbsp;&nbsp;<font color="purple">off</font>(1);</font></font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="power_level"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">power_level</font>&nbsp;&nbsp;&nbsp;[Category: System] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">power_level</font>()</font><br>Returns the current power level in volts.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="printf"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">printf</font>&nbsp;&nbsp;&nbsp;[Category: Output] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">printf</font>(<font color="blue">char</font> s[], . . .)</font><br>Prints the contents of the string referenced by s to the cursor position on the screen.<br>See the <A href="#LCD_Screen_Printing">manual</A> above for more details.          </font></font>        </dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="r_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">r_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">r_button</font>()</font><br>Reads the value (0 or 1) of the R (shoulder) button (button #256).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="random"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">random</font>&nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">random</font>(<font color="blue">int</font> m)</font><br>"Random" numbers are generated by peeking at system clock; input m isfrom <font face="Courier">2</font> to 32767.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="read_encoder"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">read_encoder</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">read_encoder</font>(<font color="blue">int</font> p)</font><br>Returns the number of pulses counted by the given encoder since it wasenabled or since the last reset, whichever was more recent. The port <font face="Courier">p</font> is in the range 8-15.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="read_extra_encoder"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">read_extra_encoder</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">read_extra_encoder</font>(<font color="blue">int</font> p)</font><br>Returns the number of pulses counted by the given encoder since it wasenabled or since the last reset, whichever was more recent. The port <font face="Courier">p</font> is in the range 16-23.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="reset_encoder"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">reset_encoder</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">reset_encoder</font>(<font color="blue">int</font> p)</font><br>Resets the counter of the given encoder to zero. For an enabledencoder, it is more efficient to reset its value than to use <font face="Courier"><font color="purple">enable_encoder</font>()</font> toclear it. The port <font face="Courier">p</font> is in the range 8-15.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="reset_extra_encoder"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">reset_extra_encoder</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">reset_extra_encoder</font>(<font color="blue">int</font> p)</font><br>Resets the counter of the given encoder to zero. For an enabledencoder, it is more efficient to reset its value than to use <font face="Courier"><font color="purple">enable_extra_encoder</font>()</font>to clear it. The port <font face="Courier">p</font> is in the range16-23.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="right_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">right_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">right_button</font>()</font><br>Reads the value (0 or 1) of the move right button (button #16).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="scale_sonar"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">scale_sonar</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">scale_sonar</font>(<font color="blue">int</font> microsecs)</font><br>This is the scaling function for the <font face="Courier" color="purple">sonar</font> function, returning the approximatemillimeters corresponding to the number of microseconds for a signalround trip.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="seconds"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">seconds</font>&nbsp;&nbsp;&nbsp;[Category: Time] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">seconds</font>()</font><br>Returns the count of system time in seconds, as a floating pointnumber. Resolution is one millisecond.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="send_sonar_ping"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">send_sonar_ping</font>&nbsp;&nbsp;&nbsp;[Category: Sensor] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">send_sonar_ping</font>(<font color="blue">int</font> p)</font><br>Routine for non-blocking sonar (<font face="Courier" color="purple">sonar</font>function blocks) - sends a ping on sonar port.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="set_beeper_pitch"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">set_beeper_pitch</font>&nbsp;&nbsp;&nbsp;[Category: Sound] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">set_beeper_pitch</font>(<font color="blue">float</font> frequency)</font><br>Sets the beeper tone to be <font face="Courier">frequency</font>(measure in Hz). The <font face="Courier" color="purple">beeper_on</font>function is then used to turn the beeper on.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="set_motion_acceleration"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">set_motion_acceleration</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">set_motion_acceleration</font>(<font color="blue">int</font> m, <font color="blue">int</font> accel)</font><br>It is recommended that the default motion acceleration set by firmwareon bootup be used. The function sets the current value used for motoracceleration for motor <font face="Courier">m</font>.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="set_motor_position_counter"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">set_motor_position_counter</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">set_motor_position_counter</font>(<font color="blue">int</font> m, <font color="blue">long</font> pos)</font><br>Sets the current motor position value for motor <font face="Courier">m</font>(a value which is continually being updated for each motor using backEMF; a typical discrimination for a given motor is on the order of 1100position "ticks" per rotation)</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="set_pid_gains"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">set_pid_gains</font>&nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;</font><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3">      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">set_pid_gains</font>(<font color="blue">int </font>kp, </font></font></font><big><span style="font-family: monospace;"><span style="color: rgb(51, 51, 255);">int</span>          </span><span style="font-family: monospace;">ki, <span style="color: rgb(51, 51, 255);">int</span> </span><span style="font-family: monospace;">kd)</span></big></dd>      </dl>      </font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></td>    </tr>    <tr>      <td valign="top"><a name="set_servo_position"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">set_servo_position</font>&nbsp;&nbsp;&nbsp;[Category: motor] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">set_servo_position</font>(<font color="blue">int</font> srv, <font color="blue">int</font> pos)</font><br>Sets the position value of the servo in port <font face="Courier">srv</font>.The value of <font face="Courier">pos</font> must be in the range 0 to255. There are 4 servo ports (0, 1, 2, 3).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="set_sonar_port"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">set_sonar_port</font>&nbsp;&nbsp;&nbsp;[Category: sensor] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">set_sonar_port</font>(<font color="blue">int</font> p)</font><br>Routine for non-blocking sonar (<font face="Courier" color="purple">sonar</font>function blocks).</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td style="vertical-align: top;"><br>      </td>      <td style="vertical-align: top;"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Times"><font face="Courier" color="purple">setpwm</font>&nbsp;&nbsp; [Category: Motors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">setpwm</font>(<font color="blue">int </font>m, </font></font></font><big><span style="font-family: monospace;"><span style="color: rgb(51, 51, 255);">int</span>          </span><span style="font-family: monospace;">dutycycle</span><span style="font-family: monospace;">)<br>          </span><small>Runs motor m at duty cycle dutycycle (values-100 to 100)</small><br>          </big></dd>      </dl>      </font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></td>    </tr>    <tr>      <td valign="top"><a name="sin"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">sin</font>&nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">sin</font>(<font color="blue">float</font> angle)</font><br>Returns the sine of <font face="Courier">angle</font>. <font face="Courier">angle</font> is specified in radians; result is inradians.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="sleep"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">sleep</font>&nbsp;&nbsp;&nbsp;[Category: Time] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">sleep</font>(<font color="blue">float</font> sec)</font><br>Waits for an amount of time equal to or slightly greater than <font face="Courier">sec</font> seconds. <font face="Courier">sec</font> isa floating point number. Example:<br>          <font face="Courier">&nbsp;&nbsp;&nbsp;<font color="darkgreen">/*wait for 1.5 seconds */</font><font color="purple"> sleep</font>(1.5);</font></font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="sonar"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">sonar</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">sonar</font>()</font><br>Returns the approximate distance in mm.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="sqrt"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">sqrt</font>&nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">sqrt</font>(<font color="blue">float</font> num)</font><br>Returns the square root of <font face="Courier">num</font>.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="start_process"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">start_process</font>&nbsp;&nbsp;&nbsp;[Category: Processes] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">start_process</font>(&lt;<i><font face="Times">function call</font></i>&gt;);</font><br>The <font face="Courier" color="purple">start_process</font> functionis used to start a process, which then runs in parallel with otheractive processes. The system keeps track of each running process byassigning a process ID number to it. <font face="Courier" color="purple">start_process</font> returns the process ID number foreach process it starts. The process runs until it finishes or until itis terminated by <font face="Courier" color="purple"><a href="#kill_process">kill_process</a></font>. Up to 4 processes (inaddition to <font face="Courier"><font color="blue">main</font></font>)can by started using <font face="Courier" color="purple">start_process</font>.The following code shows the main process creating a <font face="Courier">check_sensor</font> process, and then destroying it onesecond later:          <pre>    <font color="blue">void</font> main() {<br>        <font color="blue">int</font> pid;<br>        pid=<font color="purple">start_process</font>(check_sensor(2));<br>        <font color="purple">sleep</font>(1.0);<br>        <font color="purple">kill_process</font>(pid);<br>    }</pre>          </font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="tan"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">tan</font>&nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">float</font> <font color="purple">tan</font>(<font color="blue">float</font> angle)</font><br>Returns the tangent of <font face="Courier">angle</font>. <font face="Courier">angle</font> is specified in radians; result is inradians.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="tone"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">tone</font>&nbsp;&nbsp;&nbsp;[Category: Sound] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">void</font> <font color="purple">tone</font>(<font color="blue">float</font> frequency, <font color="blue">float</font>length)</font><br>Produces a tone at pitch <font face="Courier">frequency</font>(measured in Hertz) for length <font face="Courier">seconds</font>.Returns when the tone is finished. Both frequency and length are floats.</font></font></dd>      </dl>      </td>    </tr>    <tr>      <td valign="top"><a name="up_button"></a> </td>      <td><font face="Times"><font face="Courier" color="purple">up_button</font>&nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>      </font>      <dl>        <dd><font face="Times"><font face="Times">Format: <font face="Courier"> <font color="blue">int</font> <font color="purple">up_button</font>()</font><br>Reads the value (0 or 1) of the move up button (button #64).</font></font></dd>      </dl>      </td>    </tr>  </tbody></table></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></p><div id="banner"><A NAME='Vision'></A><h3>IC Vision API for the XBC</h3></div><div id="container"><div class="blog"><div class="blogbody"><!--1-05-06 version--><ul>  <font size="3"> <li>To use anycamera routines, be sure to put<br>    <font face="Courier">&nbsp;&nbsp;<font color="blue">#use</font> <font color="red">"xbccamlib.ic"</font></font><br>at the top of your file</li>  <li>You must call <br>    <font face="Courier">&nbsp;void&nbsp;<font color="purple">init_camera</font>();</font>    <br>to initialize the camera before any other camera functions will work</li></ul>	<h4>Tracking APIs</h4>	</font>	<ul>  <font size="3"> 	<li>Use <br>    <font face="Courier">&nbsp;int <font color="purple">track_is_new_data_available</font>();</font>    <br>to determine if tracking data is available which is newer than the data 	processed by the last call to <font face="Courier">track_update()</font>.</li>  <li>Use <br>    <font face="Courier">&nbsp;void&nbsp;<font color="purple">track_update</font>();</font>    <br>to process tracking data for a new frame and make it available forretrieval by the following calls.</li>  <li>Use <br>    <font face="Courier">&nbsp;long&nbsp;<font color="purple">track_get_frame</font>();</font>    <br>to return value is the frame number used to generate the tracking data.</li>  <li>Use <br>    <font face="Courier">&nbsp;int&nbsp;<font color="purple">track_count</font>(intch);</font> <br>to return the number of blobs available for the channel <font face="Courier">ch</font>, which is a color channel numbered 0 through2.</li>  <li> Use the following functions of the form <br>    <font face="Courier">&nbsp;int&nbsp;<font color="purple">track_<em>property</em></font>(intch, int i);</font> <br>to return the value of a given property for the blob from channel <font face="Courier">ch</font> (range 0-2), index <font face="Courier">i</font>(range 0 to <font face="Courier">track_count(ch)-1</font>). Fill in <font face="Courier"><font color="purple">track_<em>property</em></font>from one of the following: </font>    <dl>      <dd><font face="Courier">        <table id="table1">          <tbody>            <tr>              <td>              <ul>              	<li><font face="Courier">track_size</font></li>              	</ul>              </td>              <td><font face="Times">gets the number of pixels in theblob, note that this maxes out (saturates) at 32,767 if the area gets that large</font></td>            </tr>            <tr>              <td>              <ul>                <li><font face="Courier">track_x</font></li>              </ul>              </td>              <td><font face="Times">gets the pixel x coordinate of thecentroid of the blob</font></td>            </tr>            <tr>              <td>              <ul>                <li><font face="Courier">track_y</font></li>              </ul>              </td>              <td><font face="Times">gets the pixel y coordinate of theblob<br>(note: 0,0 is the upper left; 356x292 is the lower right)</font></td>            </tr>            <tr>              <td>              <ul>                <li><font face="Courier">track_confidence</font></li>              </ul>              </td>              <td><font face="Times">gets the confidence for seeing theblob as a percentage of the blob pixel area/bounding box area (range0-100, low numbers bad, high numbers good)</font></td>            </tr>                        <tr>              <td>              <ul>                <li><font face="Courier">track_bbox_left</font></li>              </ul>                   </td>              <td><font face="Times">gets the pixel x coordinate of the leftmost 				pixel in the blob</font></td>            </tr>            <tr>              <td>              <ul>                <li><font face="Courier">track_bbox_right</font></li>              </ul>                   </td>              <td><font face="Times">gets the pixel x coordinate of the rightmost 				pixel in the blob</font></td>            </tr>            <tr>              <td>              <ul>                <li><font face="Courier">track_bbox_top</font></li>              </ul>                   </td>              <td><font face="Times">gets the pixel y coordinate of the topmost 				pixel in the blob</font></td>            </tr>            <tr>              <td>              <ul>                <li><font face="Courier">track_bbox_bottom</font></li>              </ul>                   </td>              <td><font face="Times">gets the pixel y coordinate of the bottommost 				pixel in the blob</font></td>            </tr>            <tr>              <td>              <ul>                <li><font face="Courier">track_bbox_width</font></li>              </ul>                   </td>              <td><font face="Times">gets the pixel x width of the bounding box of the blob.  This is equivalent to <font face="Courier">track_bbox_right - track_bbox_left</font></font></td>            </tr>            <tr>              <td>              <ul>                <li><font face="Courier">track_bbox_height</font></li>              </ul>                   </td>              <td><font face="Times">gets the pixel y height of the bounding box of the blob.  This is equivalent to <font face="Courier">track_bbox_bottom - track_bbox_top</font></font></td>            </tr>          </tbody>        </table>        </font></dd>    </dl>  </li>  <li><font face="Times">Use</font><br>    &nbsp;void&nbsp;<font color="purple">track_set_ch_enable</font>(int ch, int val);    <br>    &nbsp;int&nbsp;<font color="purple">track_get_ch_enable</font>(int ch);    <br>    <font face="Times">to enable or disable processing tracking data for a 	particular channel <font face="Courier">ch</font> (range 0-2).&nbsp; The value passed into </font>	<font face="Courier">val</font><font face="Times"> or returned by </font>	<font color="purple">track_get_ch_enable</font><font face="Times"> is 0=disabled, 1=enabled. 	All channels are enabled by default.&nbsp; Disabling unused channels is not 	required, but can increase performance.&nbsp; </font></li>  <li><font face="Times">Use</font><br>    &nbsp;void&nbsp;<font color="purple">track_enable_orientation</font>();    <br>    &nbsp;void&nbsp;<font color="purple">track_disable_orientation</font>();    <br>    &nbsp;void&nbsp;<font color="purple">track_set_orientation_enable</font>(int val)();    <br>    &nbsp;int&nbsp;<font color="purple">track_orientation_enabled</font>();    <br>    <font face="Times">to enable or disable orientation calculation, orget the current value of this setting (0=disabled, 1=enabled). This isdisabled by default, and takes significant extra computation whenenabled.</font></li>  <li> <font face="Times">When orientation calculation is enabled, usethe following functions of the form </font><br>    &nbsp;float&nbsp;<font color="purple">track_<em>property</em></font>(intch, int i); <br>    <font face="Times"> to return the value of a givenorientation-related property for the blob from channel <font face="Courier">ch</font> (range 0-2), index <font face="Courier">i</font>(range 0 to <font face="Courier">track_count(ch)-1</font>). Fill in 	<font color="purple" face="Courier">track_<em>property</em></font>from one of the following: </font>    <dl>      <dd><font face="Times">        <table id="table2">          <tbody>            <tr>              <td>              <ul>                <li><font face="Courier">track_angle</font></li>              </ul>              </td>              <td><font face="Times">gets the angle in radians of themajor axis of the blob.  Zero is horizontal and when the left end is higher than the right end the angle will be positive.  The range is -PI/2 to +PI/2.</font></td>            </tr>            <tr>              <td>              <ul>                <li><font face="Courier">track_major_axis</font><br>                  <font face="Courier">track_minor_axis</font></li>              </ul>              </td>              <td><font face="Times">gets the length in pixels of themajor and minor axes of the bounding ellipse</font></td>            </tr>          </tbody>        </table>        </font></dd>    </dl>  </li>  <font face="Times"> <li>Use<br>    <font face="Courier">&nbsp;void&nbsp;<font color="purple">track_set_minarea</font>(intminarea);</font> <br>    <font face="Courier">&nbsp;int&nbsp;<font color="purple">track_get_minarea</font>();</font>    <br>    to set or retrieve the minimum area of a blobnecessary to consider it valid. Blobs with area below <font face="Courier">minarea</font> are ignored, and only blobs with areaabove <font face="Courier">minarea</font> are returned by the abovecalls. Default value of min area is 100.  The min area can be set interactively using the vision menus as well.</li>  <li>Use <br>    <font face="Courier">&nbsp;void&nbsp;<font color="purple">track_show_display</font>(intshow_processed, int frameskip, int channel_mask);</font> <br>to show tracking results on the Gameboy display.    <ul>      <li> <font face="Courier">show_processed</font> controls whattype of video is displayed. If it is zero then raw video will bedisplayed, meaning that the video will be shown as it comes from thecamera; if it is non-zero then processed video will be shown, meaningthat pixels matching each color channel will be shown as a differentcolor, and pixels matching no color channel will be shown as black.</li>      <li> <font face="Courier">frameskip</font> controls how manyframes of video are skipped between display updates. Smaller numberswill result in smoother video, but will heavily load the system andcause other computation to happen more slowly. Larger numbers willresult in jerkier video, but allow other computaion more time toexecute.</li>      <li> <font face="Courier">channel_mask</font> controls whichchannels blob tracking data and/or processed video is shown for. TheLSB controls channel 0, the next most significant bit controls channel1, etc. A 1 in each bit position means to show that channel, and a 0means to not show it. For example, 7 (0b111) shows all channels, 4(0b100) shows just channel 2, etc.</li>    </ul>A user may exit out of tracking display mode by hitting the B button onthe Gameboy, which is consistent with the way display modes are exitedwhen using the menu system. </li></ul>	<h4>Camera Configuration APIs</h4>	<ul>	<li>Concepts:<ul>	<li><i>White Balance</i> refers to the &quot;color temperature&quot; the camera uses 	in converting the incoming light into pixel values.&nbsp; This is necessary 	because different light sources can contain a significantly different 	balance of red and blue components.&nbsp; For example, the sun and 	incandescent lights are much redder, and fluorescent lights are much bluer.&nbsp; 	Human brains compensate for changes in lighting color very quickly, to the 	point where we are mostly unaware that the issue exists.&nbsp;	<p>Cameras, however, need to use explicit mechanisms to try to compensate 	for these changes so that things in the image look &quot;right&quot; to humans, and 	more importantly for color segmentation, so that the HSV values reported by 	the camera when looking at a given object can be fairly uniform when seen in 	a range of different lighting sources.&nbsp; </p>	<p>By default cameras turn on <i>Auto White Balance</i> (<i>AWB</i>) and 	dynamically adjust their color temperature to keep the amounts of red and 	blue in the field of view roughly balanced.&nbsp; This is fine if the 	content of the field of view <b>is</b> roughly balanced between red and blue 	and if the goal is to look good to humans in changing, arbitrary lighting 	situations.&nbsp; However, when trying to do color tracking, dynamically 	changing color temperature is generally counter productive.&nbsp; </p>	<p>Instead, you should use the <u>Vision/Camera Config</u> menu and press 	the Start button to interactively calibrate the white balance while pointing 	the camera at a white sheet of paper.&nbsp; This will adjust the <i>Red</i> 	and <i>Blue</i> components of the color temperature until the amount of each 	in the scene balances, then turn off <i>AWB</i> to lock those values in.&nbsp; 	After this procedure, it's a good idea to go to the <u>Vision/Flash Memory</u> 	menu, select &quot;Setting: &lt; Camera Config &gt;&quot;, and then &quot;Save to Flash&quot;.</li>	<li><i>Exposure</i> (range 0-154) refers to the amount of time during each 	frame that the camera spends allowing light to be detected.&nbsp; If the 	light is very bright this will be a small amount of time, since in bright 	light it doesn't take long to accumulate all the light the camera's detector 	can handle.&nbsp; If the light is dim then this will be a larger amount of 	time.&nbsp; By default the camera enables <i>Automatic Exposure Control</i> 	(<i>AEC</i>) and dynamically adjusts this value to maintain a constant 	relative percentage of &quot;bright&quot; and &quot;dark&quot; pixels.&nbsp; If you disable <i>	AEC</i> then the <i>Exposure</i> will stay at whatever value it was last set 	to until <i>AEC</i> is enabled again.&nbsp; </li>	<li><i>Gain</i> (range 0-248) controls how much the raw image integrated 	from the incoming light is multiplied in order to generate the pixel values 	reported by the camera.&nbsp; If the light is bright enough, <i>Gain</i> 	should be zero.&nbsp; When the light is not bright enough, <i>Gain</i> has 	to be higher in order to compensate or the image will be too dark to be 	useful, but the quality of the image goes down and looks grainier.&nbsp; By 	default the camera enables <i>Automatic Gain Control</i> (<i>AGC</i>) and 	dynamically adjusts this value to maintain a constant relative percentage of 	&quot;bright&quot; and &quot;dark&quot; pixels.&nbsp; If you disable <i>AGC</i> then the <i>Gain</i> 	will stay at whatever value it was last set to until <i>AGC</i> is enabled 	again.&nbsp; </li>	<li>Exposure/Gain xpoSetting:<ul>	<li>The camera will report the <i>Exposure</i> and <i>Gain</i> values which 	it is currently using independent of whether <i>AEC</i> or <i>AGC</i> are 	enabled.</li>	<li>The user can directly set the <i>Gain</i> value (which also implicitly 	disables <i>AGC</i>), but the camera does not support not support directly 	setting the <i>Exposure</i> value.</li>	<li>There are two parameters which allow the user to adjust the way the camera dynamically adjusts its <i>Exposure</i> and<i> Gain</i>:&nbsp;	<ul>	<li><i>Auto Exposure Ratio</i> (<i>AERatio</i>) (range 1- 254, default=65) 	controls the percentage of &quot;bright&quot; versus &quot;dark&quot; pixels which it tries to 	maintain: 1 = Maintain 0.5% &quot;bright&quot; pixels, 65 = 25% &quot;bright&quot;, 254 = 99.5% 	&quot;bright&quot;.&nbsp; The net effect of this is that low AERatio values make the 	image look darker, and high values make the image look brighter.</li>	<li><i>Exposure Reference Level</i> (<i>ExpRL</i>) (range 0-224, default 	160) selects the reference level voltage used for automatic setting of <i>	Exposure</i> and <i>Gain</i>.&nbsp; Higher values make the image look 	brighter, and lower values make it look darker.&nbsp; This is actually a 	3-bit value in the most significant 3 bits of a byte, so value changes are 	in increments of 32.</li></ul>	</li>	<li>When <i>AEC</i> and <i>AGC</i> are both enabled, the camera will set <i>	Gain</i> to zero if the light is bright enough and modify <i>Exposure</i> to 	achieve the desired percentage of &quot;bright&quot; pixels given the current values 	of <i>AERatio</i> and <i>ExpRL</i>.&nbsp; As the light level decreases the 	camera will increase <i>Exposure</i> until it hits the maximum value (154), 	then modify <i>Gain</i> as much as it needs to to achieve its goals or until 	it hits the maximum value (248).</li></ul>	</li></ul>	</li>	<li>Use    <br>    &nbsp;int&nbsp;<font color="purple">camera_get_awb</font>();    <br>    &nbsp;int&nbsp;<font color="purple">camera_set_awb</font>(int enable);    <br>    to get or set whether or not <i>Auto White Balance</i> is enabled (0=disabled, 1=enabled). </font></li>	<li>  <font face="Times"> Use    <br>    &nbsp;int&nbsp;<font color="purple">camera_get_wb_color_temp</font>(int color[]);    <br>    &nbsp;int&nbsp;<font color="purple">camera_set_wb_color_temp</font>(int color[]);        <br>    to get or set the red and blue components of color temperature.&nbsp; 	Calling <font color="purple">camera_set_wb_color_temp </font>implicitly 	disables <i>AWB</i>.  <font face="Courier">&nbsp;color[]</font> is an int array 	of length 2 where:</font><font face="Courier"><ul>	<li>color</font><font face="Times"><font face="Courier">[0] = red</font></li>  	</font>  <font face="Courier"> 	<li>color</font><font face="Times"><font face="Courier">[1] = blue</font>  	</font>	</ul>	<p><font face="Times">The return values are 0 for success, -1 for failure 	(fails if _array_size(color)!=2).&nbsp; If you 	want to use these functions from the interaction window you will need to use 	a block to create a </font><font face="Courier">color[]</font><font face="Times"> 	array:</font><ul>	<li>{int color[2]; camera_get_wb_color_temp(color); printf(&quot;Red=%d, 	Blue=%d\n&quot;, color[0], color[1]);}</li>	<li>{int color[]={100,200}; camera_set_wb_color_temp(color);}</li></ul>	</li>	<li><font face="Times">The following are equivalent in function, but may be 	more convenient for interactive use:</font></li>    <br>    &nbsp;int&nbsp;<font color="purple">camera_get_wb_red_temp</font>();    <br>    &nbsp;int&nbsp;<font color="purple">camera_get_wb_blue_temp</font>();	</li>  <font face="Times"> 	<li>Use    <br>    &nbsp;int&nbsp;<font color="purple">camera_get_a</font><font color="#800080">ec</font>();    <br>    &nbsp;int&nbsp;<font color="purple">camera_set_a</font><font color="#800080">ec</font>(int enable);    <br>    to get or set whether or not <i>Auto Exposure Control</i> is enabled (0=disabled, 1=enabled). </font></li>	<li>  <font face="Times"> Use        <br>    &nbsp;int&nbsp;<font color="purple">camera_get_exposure</font>();    <br>    to get the current value of <i>Exposure</i>.&nbsp; There is no set function 	for <i>Exposure</i> because the camera does not support that operation.</font></li>  <font face="Times"> 	<li>Use        <br>    &nbsp;int&nbsp;<font color="purple">camera_get_aec_ratio</font>();    <br>    &nbsp;int&nbsp;<font color="purple">camera_set_aec_ratio</font>(int val);    <br>    to get or set the value of the <i>Auto Exposure Ratio</i> (<i>AERatio</i>) (range 1- 254, 	default=65).</font></li>  <font face="Times"> 	<li>Use        <br>    &nbsp;int&nbsp;<font color="purple">camera_get_exp_ref_level</font>();    <br>    &nbsp;int&nbsp;<font color="purple">camera_set_exp_ref_level</font>(int val);    <br>    to get or set the value of the <i>Exposure Reference Level</i> (<i>ExpRL</i>) 	(range 0-224, default 160).</font></li>  <font face="Times"> 	<li>Use    <br>    &nbsp;int&nbsp;<font color="purple">camera_get_a</font><font color="#800080">gc</font>();    <br>    &nbsp;int&nbsp;<font color="purple">camera_set_a</font><font color="#800080">gc</font>(int enable);    <br>    to get or set whether or not <i>Auto Gain Control</i> is enabled (0=disabled, 1=enabled). </font></li>	<font face="Times"> 	<li>Use        <br>    &nbsp;int&nbsp;<font color="purple">camera_get_gain</font>();    <br>    &nbsp;int&nbsp;<font color="purple">camera_set_gain</font>(int val);    <br>    to get or set the value of <i>Gain</i> (range 0-248).</font></li>&nbsp; 	Calling <font color="purple" face="Times">camera_set_gain</font> also 	implicitly disabled <i>AGC</i>.</ul><font face="Times">	<h4>Color Model APIs</h4>	<ul>	<li>Color models are expressed as a range of values in the HSV (Hue, 	Saturation, Value) cube which are considered to be included within the range 	of pixels accepted by that model.&nbsp; 	<ul>	<li>Hue (range 0-359) is analogous to what we usually think of as the 	&quot;color&quot; of a pixel: Red ~= 0, Green ~= 100, Blue ~= 240. The Hue range may 	wrap, for example <i>hMin</i>=340, <i>hMax</i>=10 is a valid range.&nbsp; 	However, the distance from <i>hMax</i> to <i>hMin</i> ((360<i> + hMax</i> -	<i>hMin</i>) % 360) may not exceed 120.</li>	<li>Saturation (range 0 - 223) is how pure and intense the hue is: 0 = 	totally unsaturated, such as black, white, or grey; 223 = totally saturated, 	such as neon orange, fire-engine red, etc.&nbsp; Hue is most reliable, and 	therefore color distinction is more robust, for pixels with high Saturation.&nbsp; 	If Saturation is too low, then the Hue calculation will be fairly random.&nbsp; 	Therefore you can set <i>sMin</i>, the minimum acceptable Saturation value, 	but <i>sMax</i> is the maximum possible value of 223 for color tracking.</li>	<li>Value (range 0-223) is how dark or bright the pixel is: 0 = black, 223 = 	bright.&nbsp; Hue is most reliable, and therefore color distinction is more 	robust, for pixels with high Value.&nbsp; If Value is too low, then the Hue 	calculation will be fairly random.&nbsp; Therefore you can set <i>vMin</i>, 	the minimum acceptable Value, but <i>vMax</i> is the maximum possible value 	of 223 for color tracking.</li></ul>	</li>	<li>Use <br><font face="Courier">&nbsp;int <font color="purple">color_get_model</font>(int model_num, int model[]);</font>	<br><font face="Courier">&nbsp;int <font color="purple">color_set_model</font>(int model_num, int model[]);</font>	<br>to get or set the parameters of color model <font face="Courier">model_num</font> (range 0-2) 	currently in use.&nbsp;   	<font face="Courier">model[]</font> is an int array 	of length 4 where:<ul>	<li><font face="Courier">model[0] = hMin</font></li>	<li><font face="Courier">model[1] = hMax</font></li>  	</font><font face="Courier">	<li>model[2] = sMin</li>	<li>model[3] = vMin</li></ul>  	</font>	<p><font face="Times">The return values are 0 for success, -1 for failure 	(fails if _array_size(model)!=4 or arguments out of range).&nbsp; If you 	want to use these functions from the interaction window you will need to use 	a block to create a </font><font face="Courier">model[]</font><font face="Times"> 	array:</font><ul>	<li><font face="Times">{int model[4]; color_get_model(0, model); printf(&quot;H=(%d-&gt;%d), 	S&gt;=%d, V&gt;=%d\n&quot;, model[0], model[1], model[2], model[3]);}</font></li>	<li><font face="Times">{int model[]={0, 100, 200, 200}; 	color_set_model(0,model);}</font></li></ul></li>	<li><font face="Times">The following are equivalent in function, but may be 	more convenient for interactive use:</font></li>	<br>    &nbsp;int&nbsp;<font color="purple">color_get_ram_hmin</font>(int model_num);    <br>    &nbsp;int&nbsp;<font color="purple">color_get_ram_hmax</font>(int model_num);    <br>    &nbsp;int&nbsp;<font color="purple">color_get_ram_smin</font>(int model_num);    <br>    &nbsp;int&nbsp;<font color="purple">color_get_ram_smax</font>(int model_num);    <br>    &nbsp;int&nbsp;<font color="purple">color_get_ram_vmin</font>(int model_num);    <br>    &nbsp;int&nbsp;<font color="purple">color_get_ram_vmax</font>(int model_num);    <br>    &nbsp;int&nbsp;<font color="purple">color_set_ram_model</font>(int model_num, int hmin, int hmax, int smin, int vmin);</ul><font face="Times">  	</font></font>	<ul>  </font></ul>	</div></div></div><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Courier"><font face="Times"><a name="Simulator"></a><br clear="all"></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font><h2><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Courier"><font face="Times">Using the IC Simulator</font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></h2><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Courier"><font face="Times"><br><br><b>1. Setting up to use the simulator</b><br>There are 3 requirements that must be fulfilled in order to use thesimulator:<br></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font><ul>  <li><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Courier"><font face="Times">A board that has a valid simulatorlibrary must be loaded. If a board does not have a simulator library, awarning will be shown when the user tries to activate the simulator.    </font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></li>  <li><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Courier"><font face="Times">A valid IC file must be loaded    </font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></li>  <li><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Courier"><font face="Times">The IC file must compile with noerrors    </font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></li></ul><p><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Courier"><font face="Times">After these conditions are met, the simulator   can be activated.<br>  <br>  <b>2.Opening the simulator</b> <br>  With the IC file you would like to simulate selected in the tab interface, hit   the "simulate" button on the top toolbar. This will open the simulator window,   with the current IC file loaded and ready to run.<br>  <br>  <b>3. Running the simulator</b> <br>  To start the simulator running, hit the "Execute" button at the bottom of the   simulator window. This will execute whatever code is currently loaded into the   simulator. To pause execution, hit the pause button. To resume it, hit the execute   button again. To reset the simulator back to its starting state (similar to   turning a controller board off and back on), hit the reset button. To exit the   simulator and return to the IC compiler window, hit the cancel button.<br>  <br>  <b>4. A tour of the simulator window</b> <br>  The simulator provides all the inputs and outputs of the controller board it   is simulating, including sensors, motors, and any board specific features.<br>  Sensors are located in the upper left hand box. Sensor type is denoted by the   letter next to the sensor number, 'a' standing for analog sensor, 'd' for digital.   The values for sensors may be set by either typing in the value in the corresponding   box, or using the up and down arrows to change the value. The simulator does   not need to be paused in order to change the value, and the program that is   currently running will react as soon as any change is made.<br>  In addition to the usual analog and digital sensors, boards might have certain   unique features such as buttons and knobs (i.e. the start/stop buttons on the   Handyboard, Prgm/View on the RCX, etc...). These features are available in the   box directly below the sensors, and are settable through the same methods as   the sensors.<br>  The right side of the simulator window houses the help and output features.<br>  In the upper right hand corner is the Show Diagram button. By pressing the board   diagram button, the user can bring up a picture of the controller board being   simulated, in order to relate port positions to their physical positions on   the actual board.<br>  Below this is the Print Buffer display. This display is used to show what would   usually be on the screen of the controller board, and is customized to show   the text in the same format as it will be shown on the controller board.<br>  Finally, the motor output values are displayed below the Print Buffer window.   These reflect the PWM settings of the motors available on the board.<br>  <br>  <b>5. The simulator interaction and global windows</b> <br>  The simulator has an interaction feature, similar to using a real controller   board. Users may type commands into the interaction window and it will return   the results from the current state of the simulated board. In addition, there   is now a global tracking window. This displays the names, types, addresses,   and values of globals in the currently loaded program, and updates their values   as they change during the course of the program's execution.</font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></p><p><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font size="6"><font size="2"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="5"><font size="3"><font size="4"><font size="3"><font size="4"><font size="3"><font size="5"><font size="3"><font face="Courier"><font face="Times"><br>  <b>6. iROBOsim</b> <br>  When using the XBC or XBC+Create you can insert into any program the command   iROBOinit(&lt;world&gt;) where world can be EMPTYWORLD, RULERWORLD, ARENAWORLD,   BIGEMPTYWORLD, or BIGWORLD.</font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font></font>   This is a noop to code loaded onto the XBC, however if the code is loaded into   the simulator it will open up a graphic window and display a robot similar to   the Create. With the XBC+Create target all of the Create motion commands may   be used along with the bump sensors (gc_lbump and gc_rbump), distance and angle   sensors. Other commands are simply noops in the simulator. For the XBC target   motors 0 and 1 are used for the drive wheels and digital sensors 15 and 8 are   used for the left and right front bumpers. Both targets use digitals 9 &amp;   14 for the right and left rear bumpers. </p></body></html>